How to use Apify Actors with Claude Code

You get a one-line claude mcp add command that gives Claude Code the tools of the Google Maps Actors in this catalogue, so a prompt such as 'find coffee shops in Denver with phone and website' returns rows from a schema-backed Actor instead of a web summary. If you want all of Apify in Claude Code instead, install the Apify plugin; the scoped URL on this page loads only the Actors you pick, which keeps the tool list short.

Checked 2026-11-12

Do it now

The config for every Google Maps Actor in the catalogue (6 in this bundle), for each client. Claude Code is first.

Claude Code configterminal or .mcp.json

claude mcp add --transport http apify-google "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-business-lead-finder-with-email,nimbryxo-studio/google-maps-review-and-contributor-activity,vexaloom-labs/google-maps-business-finder-with-hours-ratings,dataspryva/google-maps-business-lead-and-email-finder,dataspryva/google-maps-related-place-and-competitor-finder,nimbryxo-studio/google-maps-popular-times-and-live-busyness"

Run the command in your project folder. Add --scope user to make it available in every project.
Start Claude Code, type /mcp, pick the server and sign in to Apify in the browser window.
No browser sign-in? Add --header "Authorization: Bearer YOUR_APIFY_TOKEN" to the command instead.

Sign-in: OAuth sign-in on first use, or a token header.

Claude Desktop configclaude_desktop_config.json

{
  "mcpServers": {
    "apify-google": {
      "command": "npx",
      "args": [
        "-y",
        "@apify/actors-mcp-server",
        "--tools",
        "fetch-actor-details,vexaloom-labs/google-maps-business-lead-finder-with-email,nimbryxo-studio/google-maps-review-and-contributor-activity,vexaloom-labs/google-maps-business-finder-with-hours-ratings,dataspryva/google-maps-business-lead-and-email-finder,dataspryva/google-maps-related-place-and-competitor-finder,nimbryxo-studio/google-maps-popular-times-and-live-busyness"
      ],
      "env": {
        "APIFY_TOKEN": "YOUR_APIFY_TOKEN"
      }
    }
  }
}

Easiest: open Customize, then Connectors, choose Add custom connector, paste the server URL (the ChatGPT tab shows it on its own) and sign in to Apify.
Local alternative (needs Node.js): merge this into claude_desktop_config.json (Settings, Developer, Edit config) and replace YOUR_APIFY_TOKEN.
Restart Claude Desktop and enable the server from the tools menu in a chat.

Sign-in: Connector with OAuth, or a token in the local config.

Cursor config~/.cursor/mcp.json

{
  "mcpServers": {
    "apify-google": {
      "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-business-lead-finder-with-email,nimbryxo-studio/google-maps-review-and-contributor-activity,vexaloom-labs/google-maps-business-finder-with-hours-ratings,dataspryva/google-maps-business-lead-and-email-finder,dataspryva/google-maps-related-place-and-competitor-finder,nimbryxo-studio/google-maps-popular-times-and-live-busyness",
      "headers": {
        "Authorization": "Bearer ${env:APIFY_TOKEN}"
      }
    }
  }
}

Save as ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one project. Merge with servers you already have.
Set APIFY_TOKEN in the environment Cursor starts from, or replace ${env:APIFY_TOKEN} with your token.
Open Cursor Settings, then MCP, and check that the server lists its tools.

Sign-in: Token read from the APIFY_TOKEN environment variable.

VS Code config.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apify-token",
      "description": "Apify API token",
      "password": true
    }
  ],
  "servers": {
    "apify-google": {
      "type": "http",
      "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-business-lead-finder-with-email,nimbryxo-studio/google-maps-review-and-contributor-activity,vexaloom-labs/google-maps-business-finder-with-hours-ratings,dataspryva/google-maps-business-lead-and-email-finder,dataspryva/google-maps-related-place-and-competitor-finder,nimbryxo-studio/google-maps-popular-times-and-live-busyness",
      "headers": {
        "Authorization": "Bearer ${input:apify-token}"
      }
    }
  }
}

Save as .vscode/mcp.json in your workspace.
Start the server from the file or the MCP servers view. VS Code asks for the token once and stores it securely.
Use the tools from Copilot Chat in agent mode.

Sign-in: Token prompted once and stored by VS Code.

ChatGPT configPlugins > Add custom MCP server

https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-business-lead-finder-with-email,nimbryxo-studio/google-maps-review-and-contributor-activity,vexaloom-labs/google-maps-business-finder-with-hours-ratings,dataspryva/google-maps-business-lead-and-email-finder,dataspryva/google-maps-related-place-and-competitor-finder,nimbryxo-studio/google-maps-popular-times-and-live-busyness

In ChatGPT on the web, open Plugins, select + and choose Add custom MCP server.
Name it, paste the URL under Connection as the Server URL and choose OAuth for authentication.
Accept the risk warning (I understand and want to continue), select Create as a plugin, then install the plugin from your plugins, sign in to Apify and use it in a new chat.

Sign-in: OAuth sign-in with your Apify account.

Codex CLI config~/.codex/config.toml

[mcp_servers.apify-google]
url = "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-business-lead-finder-with-email,nimbryxo-studio/google-maps-review-and-contributor-activity,vexaloom-labs/google-maps-business-finder-with-hours-ratings,dataspryva/google-maps-business-lead-and-email-finder,dataspryva/google-maps-related-place-and-competitor-finder,nimbryxo-studio/google-maps-popular-times-and-live-busyness"
bearer_token_env_var = "APIFY_TOKEN"

Add the block to ~/.codex/config.toml, or .codex/config.toml in a project.
Export APIFY_TOKEN in the shell that starts Codex. Or skip the token line and run codex mcp login to sign in.
Start codex and type /mcp to check that the tools are listed.

Sign-in: Token read from the APIFY_TOKEN environment variable.

Gemini CLI configterminal (writes ~/.gemini/settings.json)

gemini mcp add -t http -s user -H "Authorization: Bearer $APIFY_TOKEN" apify-google "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-business-lead-finder-with-email,nimbryxo-studio/google-maps-review-and-contributor-activity,vexaloom-labs/google-maps-business-finder-with-hours-ratings,dataspryva/google-maps-business-lead-and-email-finder,dataspryva/google-maps-related-place-and-competitor-finder,nimbryxo-studio/google-maps-popular-times-and-live-busyness"

Export APIFY_TOKEN first: the shell expands it and Gemini CLI saves the header, token included, in plain text in ~/.gemini/settings.json (keep that file private). In PowerShell write $env:APIFY_TOKEN instead of $APIFY_TOKEN. Drop -s user to save it in the project's .gemini/settings.json.
Start gemini and type /mcp to check that the server is connected and lists its tools.
Saved by hand, a remote server uses the httpUrl key for streamable HTTP (url means the older SSE transport).

Sign-in: Token header saved by gemini mcp add.

n8n AI Agent configMCP Client Tool node

https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-business-lead-finder-with-email,nimbryxo-studio/google-maps-review-and-contributor-activity,vexaloom-labs/google-maps-business-finder-with-hours-ratings,dataspryva/google-maps-business-lead-and-email-finder,dataspryva/google-maps-related-place-and-competitor-finder,nimbryxo-studio/google-maps-popular-times-and-live-busyness

Add an AI Agent node, then attach an MCP Client Tool node to its tool input.
Paste the URL as the endpoint and choose HTTP Streamable as the transport.
Choose Bearer auth and create a credential that holds your Apify token.

Sign-in: Bearer auth credential.

Validated, not executed: 7 of 7 checks pass

Uses Apify's hosted MCP endpoint over HTTPS
The tools parameter lists exactly the chosen Actors as owner/name
JSON configs parse and use the client's top-level key and the same URL
Codex TOML has a [mcp_servers.<name>] table with url and bearer_token_env_var
CLI commands quote the same URL and use the streamable HTTP transport
One-click install links decode back to the same URL and carry no token
Only placeholders, no real token

Pick which Google Maps Actors go in the bundle

Claude Code talks to Apify through the hosted MCP server at https://mcp.apify.com. You sign in with OAuth or pass an Apify API token, and the tools parameter in the URL decides which Actors Claude Code can call. The server allows up to 30 requests per second per user, which is far more than an interactive session needs.

What you need

Claude Code installed and signed in.
An Apify account: sign in through OAuth when Claude Code asks, or export an APIFY_TOKEN from Apify Console, Settings, API and integrations.
The scoped server URL from the Do it now block, which lists fetch-actor-details plus the Google Maps Actors.
Optional: the Apify plugin for Claude Code, if you would rather load every Apify tool and the Apify Agent Skills in one install.

Where it breaks

The usual failure is a missing or wrong token: Claude Code shows the server as failed or the first tool call answers unauthorized. Run /mcp, check that the apify server is connected, and sign in again or re-export APIFY_TOKEN before starting Claude Code. A second failure is asking for data the Actor does not return; open the Actor page here first and check its output fields, then name those fields in your prompt.

Method

Copy the claude mcp add command from the Do it now block and run it in your terminal; it registers the hosted server with fetch-actor-details and the Google Maps Actors in its tools list.
Start Claude Code, run /mcp and confirm the apify server is connected; if it asks you to authenticate, complete the Apify sign-in in your browser.
Ask for a structured dataset and name the fields you want, for example: use the Google Maps lead finder to list bakeries in Lyon with name, address, phone and website as a table.
Read the Actor run that Claude Code starts, then ask it to save the rows as CSV or JSON in your project so you can reuse them without a second run.
If you want every Apify tool instead of a scoped list, run /plugin marketplace add apify/apify-claude-code-plugin, then /plugin install apify@apify and /reload-plugins, and enable and authenticate plugin:apify:apify in /mcp.

Troubleshooting

Why does the client say Unauthorized or invalid token?

Every Apify Actor tool needs a signed-in Apify account. Reconnect the server so the OAuth sign-in runs again, or switch to the token variant: an Authorization: Bearer header with an API token from Apify Console, Settings, API and integrations. For a local server the token must be in the server's own env block, not only in your shell.

Source: Apify MCP server README

Why did my agent's tool list change after an update?

Without a tools parameter Apify's server loads its default tool set, which changes between releases. The URLs on this site pin the tools with ?tools=, so the agent always gets the same Actor tool plus fetch-actor-details. Apify's README gives the same advice for production.

Source: Apify MCP server README

What happens when the agent sends input the Actor rejects?

The server answers with the Actor's input schema, so the agent can fix the arguments and call again. The fetch-actor-details tool in every scoped URL lets it read that schema before the first call.

Source: Apify MCP server README

Claude Code shows Needs authentication. Why?

The server is added but not signed in. Type /mcp in an interactive session and authenticate, or run claude mcp login with the server name. Headless runs with claude -p cannot complete OAuth, so sign in once interactively or use the --header token variant.

Source: Claude Code MCP documentation

Claude Code warns that a tool result is too large. What can I change?

Claude Code warns above 10,000 tokens of tool output and caps it at 25,000 by default (MAX_MCP_OUTPUT_TOKENS raises it). Ask the agent for fewer results per call, for example a lower result limit for the Actor.

Source: Claude Code MCP documentation

Every fix in one place

Questions

Should I use the Apify plugin or the scoped URL?

Use the plugin when you want all of Apify, including its Agent Skills, in Claude Code. Use the scoped URL when you want one or a few Actors, which keeps the tool list and the token use small.

Do I have to paste an API token?

No. The hosted server supports OAuth, so Claude Code can open the Apify sign-in in your browser. A token in the APIFY_TOKEN variable works too, for example on a server.

Why does Claude Code not see the Actor?

The Actor is missing from the tools list in the server URL, or the server did not connect. Run /mcp to check the connection and compare the URL with the one on the Actor's page.

Who pays for the runs?

Your Apify account. Each Actor page shows its Store price and the start fee per run, plus Apify platform usage.

Sources

Apify MCP documentation, checked 2026-11-09
Claude Code MCP, checked 2026-11-09