diff --git a/sources/platform/integrations/ai/chatgpt.md b/sources/platform/integrations/ai/mcp/chatgpt.md similarity index 97% rename from sources/platform/integrations/ai/chatgpt.md rename to sources/platform/integrations/ai/mcp/chatgpt.md index 8b5259baa0..062c61534c 100644 --- a/sources/platform/integrations/ai/chatgpt.md +++ b/sources/platform/integrations/ai/mcp/chatgpt.md @@ -40,7 +40,7 @@ Before connecting ChatGPT to Apify, you'll need: 3. Select **Create** to proceed to the authentication page. You’ll be redirected to the Apify website to authorize ChatGPT to access your Apify account. -![ChatGPT Create connection](../images/chatgpt-connector.png) +![ChatGPT Create connection](../../images/chatgpt-connector.png) Once authorized, you'll return to ChatGPT and see a success message with a list of tools available from the Apify MCP server. @@ -63,7 +63,7 @@ Once your connector is ready: You'll need to grant permission for each Apify tool when it's used for the first time. You should see ChatGPT calling Apify tools - such as the [RAG Web Browser](https://apify.com/apify/rag-web-browser) - to gather information. -![ChatGPT Apify tools](../images/chatgpt-with-rag-web-browser.png) +![ChatGPT Apify tools](../../images/chatgpt-with-rag-web-browser.png) ## Limitations diff --git a/sources/platform/integrations/ai/mcp/claude-desktop.md b/sources/platform/integrations/ai/mcp/claude-desktop.md new file mode 100644 index 0000000000..54a3fe9a5d --- /dev/null +++ b/sources/platform/integrations/ai/mcp/claude-desktop.md @@ -0,0 +1,189 @@ +--- +title: Claude Desktop integration +sidebar_label: Claude Desktop +description: Set up the Apify MCP server in Claude Desktop using one-click install, remote server, or local stdio, and troubleshoot common issues. +sidebar_position: 1.5 +slug: /integrations/claude-desktop +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/integrations/mcp) to give your conversations access to thousands of Actors from [Apify Store](https://apify.com/store). Once connected, Claude can search for, run, and retrieve results from Actors directly in your chat. + +## Prerequisites + +- An [Apify account](https://console.apify.com/sign-up) with an [API token](https://console.apify.com/account#/integrations) +- [Claude Desktop](https://claude.ai/download) installed +- [Node.js](https://nodejs.org/) version 18 or higher (only required for [local stdio setup](#local-stdio-server)) + +## Connect to Apify + +Choose one of the following methods, from simplest to most flexible: + +- [One-click installation](#one-click-installation-recommended) with the `.mcpb` file (recommended) +- [Remote server configuration](#remote-server-manual-configuration) (no local dependencies) +- [Local stdio server](#local-stdio-server) (development, testing, or offline access) + +### One-click installation (recommended) + +Download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/apify-mcp-server/releases/latest/download/apify-mcp-server.mcpb). Claude Desktop automatically registers the Apify MCP server and prompts you to approve the connection. + +:::note Direct install from Claude Desktop may fail + +Installing Apify directly from Claude Desktop's connector list may fail silently or show connection errors. Use the `.mcpb` file above or [manual configuration](#remote-server-manual-configuration) instead. See [troubleshooting](#unable-to-connect-to-extension-server-error) for details. + +::: + +### Remote server (manual configuration) + +The remote server at `https://mcp.apify.com` is the simplest manual setup - no local dependencies required. + +1. Open Claude Desktop. +1. Go to **Settings** > **Developer** > **Edit Config**. +1. Add the Apify MCP server configuration: + + + + +```json +{ + "mcpServers": { + "apify": { + "url": "https://mcp.apify.com" + } + } +} +``` + +On first connection, your browser opens to sign in to Apify and authorize the connection. This OAuth flow keeps your API token secure. + + + + +```json +{ + "mcpServers": { + "apify": { + "url": "https://mcp.apify.com", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +Replace `` with your API token from the [Integrations section](https://console.apify.com/account#/integrations) in Apify Console. + + + + +### Local stdio server + +Run the MCP server locally for development, testing, or when you need offline access. This method requires Node.js. + +1. Open Claude Desktop. +1. Go to **Settings** > **Developer** > **Edit Config**. +1. Add the following configuration: + +```json +{ + "mcpServers": { + "actors-mcp-server": { + "command": "npx", + "args": ["-y", "@apify/actors-mcp-server"], + "env": { + "APIFY_TOKEN": "" + } + } + } +} +``` + +Replace `` with your API token from the [Integrations section](https://console.apify.com/account#/integrations) in Apify Console. + +:::info Output schema inference + +The local stdio server does not support output schema inference for structured Actor results. Use the [remote server](#remote-server-manual-configuration) to get automatic output schemas with field-level type information. + +::: + +## Verify the connection + +1. Restart Claude Desktop after saving configuration changes. +1. Open a new conversation. +1. Check that Apify tools are available in the tools list. +1. Test with a prompt like: "Search for web scraping Actors on Apify." + +## Troubleshooting + + + +#### Tools fail to load + +The MCP server shows as connected but Apify tools don't appear in the tools list, or Claude doesn't recognize any Apify tools in conversation. + +- _Restart Claude Desktop._ Configuration changes only take effect after a restart. +- _Check the config file location._ Verify you edited the correct file: + - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` + - Windows: `%APPDATA%\Claude\claude_desktop_config.json` +- _Validate JSON syntax._ Ensure there are no trailing commas, missing quotes, or mismatched brackets. Paste your config into a JSON validator if needed. + +#### "Unable to connect to extension server" error + +This error commonly appears when installing from the Claude Desktop connector directory. In some cases, the MCP server starts and communicates correctly, but Claude Desktop still shows the error. + +- _Uninstall and reinstall the extension._ In Claude Desktop, disable the Apify extension, remove it, then add it again. +- _Switch to manual configuration._ If reinstalling doesn't help, use the [remote server](#remote-server-manual-configuration) or [local stdio](#local-stdio-server) setup instead of the connector directory. +- _Verify the server URL._ For remote setup, use exactly `https://mcp.apify.com` with no trailing slash. +- _Check your network._ Ensure your firewall or VPN is not blocking the connection. +- _For local stdio setup:_ Confirm Node.js version 18 or higher is installed by running `node -v` in your terminal. + +#### Corrupted npx cache + +A stale or corrupted npx cache can prevent the local server from starting. Clear the cache and retry: + +- macOS and Linux: + + ```bash + rm -rf ~/.npm/_npx + ``` + +- Windows: + + ```bash + rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx + ``` + +After clearing the cache, restart Claude Desktop to re-download the server package. + +#### Authentication errors + +Authentication errors occur when the MCP server can't verify your identity. You may see "Unauthorized" or "Invalid token" messages, or Actor runs may fail silently. + +- _Check your API token._ Verify the token in the [Integrations section](https://console.apify.com/account#/integrations) of Apify Console. +- _For local stdio setup:_ Ensure the `APIFY_TOKEN` environment variable is set correctly in your config file. +- _For remote OAuth:_ Remove and re-add the Apify MCP server in Claude Desktop to re-authorize. + +#### Check Claude Desktop logs + +If the above steps don't resolve your issue, check the Claude Desktop logs for MCP-related errors: + +- macOS: `~/Library/Logs/Claude/` +- Linux: `~/.config/Claude/logs/` +- Windows: `%APPDATA%\Claude\logs\` + +Look for files with `mcp` in the name for server-specific error messages. + +## Known limitations + +- The Claude Desktop connector directory may not install Apify correctly. Use the [`.mcpb` file](#one-click-installation-recommended) or [manual configuration](#remote-server-manual-configuration) instead. +- Multi-agent cowork mode may not pass MCP tool results between agents reliably when using the local stdio server. +- Some Claude Desktop versions have inconsistent behavior with remote MCP server connections. Update to the latest version if you experience issues. + +## Next steps + +- [Apify MCP server](/integrations/mcp) - Explore tool selection, available tools, telemetry, and rate limits +- [Apify MCP server configurator](https://mcp.apify.com) - Select tools visually and copy configuration +- [Apify MCP server on GitHub](https://github.com/apify/apify-mcp-server) - Report bugs and suggest features diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp/index.md similarity index 97% rename from sources/platform/integrations/ai/mcp.md rename to sources/platform/integrations/ai/mcp/index.md index 3842045fc5..88f114a1a1 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp/index.md @@ -17,7 +17,7 @@ using [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-star discover and run Actors from [Apify Store](https://apify.com/store), access storages and results, and enables AI coding assistants to access Apify documentation and tutorials. -![Apify MCP server](../../images/apify_mcp_server.png) +![Apify MCP server](../../../images/apify_mcp_server.png) ## Prerequisites @@ -233,6 +233,8 @@ To manually configure Apify's MCP server for Claude Desktop: Replace `` with your actual Apify API token from the [Integrations section](https://console.apify.com/account#/integrations). +For detailed setup options and troubleshooting, see the [Claude Desktop integration guide](/integrations/claude-desktop). + @@ -431,6 +433,12 @@ documentation queries. If you exceed this limit, you'll receive a `429` response ## Troubleshooting +:::tip Claude Desktop issues + +For Claude Desktop-specific troubleshooting (tools not loading, connection errors, corrupted cache), see [Claude Desktop troubleshooting](/integrations/claude-desktop#troubleshooting). + +::: + ##### Authentication errors - _Check your API token_: Verify that your Apify API token is correct. You can find it in the **Integrations** section of the [Apify Console](https://console.apify.com/account#/integrations). Without a valid token, the server cannot start Actor runs.