Prospect Locally
Articles

Get Google Maps leads from Claude Code or Codex

A coding agent can already read your files, run your tests, and call an API. This article shows how to point Claude Code or Codex at a lead-search service so that you can ask for “plumbers in Austin, with emails and mobile numbers” in the same terminal where you write code, and get a CSV back. It covers the connection, the order in which the agent calls the tools, how to keep credit spending under your control, and how the export works.

Connect with an API key

Two kinds of client connect to the Prospect Locally MCP server. Chat assistants such as ChatGPT and claude.ai sign in through a consent screen, and the connector article covers that path. Coding agents such as Claude Code, Cursor, and Codex have no browser consent screen, so they send an API key in a header instead.

  1. Open the API keys screen in the app and create a key. A key starts with lp_, the app shows it once, and you can revoke it later. An account can hold up to five active keys, so you can give each machine or project its own.
  2. Copy the MCP server address from the “Connect your AI” block on the home page or from the MCP section of the docs. The address ends in /api/mcp.
  3. Add the server to your agent with the header Authorization: Bearer <your key>.

In Claude Code, the command has this shape:

claude mcp add --transport http prospect-locally https://your-app-address/api/mcp --header "Authorization: Bearer lp_example_key"

Replace lp_example_key with your own key and the address with the one from the docs. Codex and Cursor take the same two values, a server address and an Authorization header, in their MCP settings. Follow each tool’s own documentation for where those settings live, because the file format differs from tool to tool and changes between releases.

Keep the key out of any file you commit. Put it in an environment variable or in your tool’s local settings, and revoke it from the API keys screen if it ever lands in a repository.

The order the agent calls the tools

The server exposes 19 tools. For a one-off search, the agent needs four of them, and it should call them in this order:

  1. find_location turns a place name such as “Austin” into a location_code. It takes a query of two or more characters, returns up to eight matches, and costs no credits.
  2. search_businesses starts the search. It takes a keyword, the location code, and a depth of 100, 300, 500, or 700 results (300 by default). It spends credits up to the depth, and credits for results that you do not receive come back.
  3. search_status takes the job ID and reports progress. A search is enriching while the owner, email, phone, and website data are still being collected, and completed when the work is done. The agent calls this tool repeatedly, and each call is free.
  4. get_results reads the leads. It returns trimmed records, 50 rows by default and at most 200 per call, so a long list takes more than one call with the page parameter. It accepts the four filters has_website, has_email, has_phone, and has_mobile_phone, which combine with AND.

When you ask for leads from many cities, a state, or a country, the agent should switch to a campaign, which the region article explains. A campaign is saved, runs one location at a time, and removes duplicates across its locations.

Ask for the credit cost before each spend

An agent that can spend credits needs a rule about when to ask you first. The setup prompts on the home page end with this sentence, and you can paste it into your own instructions as well: “Tell me the credit cost before searching, enriching or starting a campaign.”

With that rule in place, a request for 300 plumbers in Austin produces a message such as “this search can use up to 300 credits, and you have 1,200 left; shall I run it?” before any credit moves. The agent can read your balance with check_credits, which costs nothing. The same rule covers enrich_domains, which charges one credit for each domain and accepts at most ten domains per call, and verify_phones, which charges per number.

The server also limits what a mistake can cost. An agent sees and spends only the credits of the account that owns the key, and a call that needs more credits than you hold fails instead of going into debt. For a stricter limit, create a separate account for agent work and buy only the credits you are willing to let it use.

Export the result as a CSV

There are two routes to a file, and the agent should pick the one that matches the work it did.

  • After a campaign: export_campaign takes the campaign ID and a format of simple, advanced, gohighlevel, instantly, or oneclick. It returns an export ID and a download link, and get_export reports the status of a file that is still being built. The link stays valid for 1 hour.
  • After a one-off search: the agent calls the REST endpoint GET /api/v1/job/<job id>/results with a format parameter and the header x-api-key: lp_example_key, then writes the response to a file. The same key works for the REST API and for the MCP server.

Choose the format that matches the tool that will receive the file. The Simple CSV has 17 columns for a spreadsheet, the Advanced CSV carries every field, and the other three match the import screens of the tools in their names.

A short session

Here is what a good session looks like when the rules above are in place:

  1. You type: “Find roofers in Denver that have an email address, and export them for Instantly.”
  2. The agent calls find_location and check_credits, then states the cost and asks.
  3. You answer yes. The agent calls search_businesses and polls search_status.
  4. The agent reads the leads with get_results and has_email set to true.
  5. The agent fetches the Instantly format and saves it next to your project files.

If you want the agent to follow these rules without being told each time, save the skill file in your project. To try the REST calls before you spend anything, the documentation has demo endpoints that need no key and no credits.