|
| 1 | +--- |
| 2 | +title: Claude Desktop integration |
| 3 | +sidebar_label: Claude Desktop |
| 4 | +description: Learn how to set up the Apify MCP server in Claude Desktop using the remote server or one-click connector install, and troubleshoot common issues. |
| 5 | +sidebar_position: 2 |
| 6 | +slug: /integrations/claude-desktop |
| 7 | +--- |
| 8 | + |
| 9 | +import Tabs from '@theme/Tabs'; |
| 10 | +import TabItem from '@theme/TabItem'; |
| 11 | +import ThirdPartyDisclaimer from '@site/sources/_partials/_third-party-integration.mdx'; |
| 12 | + |
| 13 | +Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/platform/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. |
| 14 | + |
| 15 | +<ThirdPartyDisclaimer /> |
| 16 | + |
| 17 | +## Prerequisites |
| 18 | + |
| 19 | +- An [Apify account](https://console.apify.com/sign-up) |
| 20 | +- [Claude Desktop](https://claude.ai/download) installed |
| 21 | + |
| 22 | +## Connect to Apify |
| 23 | + |
| 24 | +Choose one of the following methods: |
| 25 | + |
| 26 | +- [Remote server](#remote-server-recommended) - recommended, automatic updates, OAuth support, no local dependencies |
| 27 | +- [One-click installation](#one-click-installation) - install from the connector directory |
| 28 | + |
| 29 | +### Remote server (recommended) |
| 30 | + |
| 31 | +The remote server at `https://mcp.apify.com` is the recommended way to connect. Key advantages: |
| 32 | + |
| 33 | +- Automatic updates - always runs the latest version of the Apify MCP server |
| 34 | +- OAuth authentication - secure sign-in through your browser, no API token needed |
| 35 | +- No local dependencies - nothing to install or maintain on your machine |
| 36 | + |
| 37 | +To set up the remote server, [add a custom connector](https://support.claude.com/en/articles/11175166) in Claude Desktop and use `https://mcp.apify.com` as the server URL. |
| 38 | + |
| 39 | +On first connection, your browser opens to sign in to Apify and authorize the connection. |
| 40 | + |
| 41 | +### One-click installation |
| 42 | + |
| 43 | +Search for "Apify" in the [Claude Desktop connector directory](https://support.claude.com/en/articles/11175166) and install the connector. |
| 44 | + |
| 45 | +Alternatively, download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb) to register the connector automatically. |
| 46 | + |
| 47 | +## Verify the connection |
| 48 | + |
| 49 | +1. Restart Claude Desktop after saving configuration changes. |
| 50 | +1. Open a new conversation. |
| 51 | +1. Check that Apify tools are available in the tools list. |
| 52 | +1. Test with a prompt like: "Search for web scraping Actors on Apify." |
| 53 | + |
| 54 | +## Troubleshooting |
| 55 | + |
| 56 | +<!-- markdownlint-disable MD001 --> |
| 57 | + |
| 58 | +If the steps below don't resolve your issue, [submit a GitHub issue](https://github.com/apify/apify-mcp-server/issues) or contact [Apify support](https://apify.com/contact). |
| 59 | + |
| 60 | +#### Tools fail to load |
| 61 | + |
| 62 | +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. |
| 63 | + |
| 64 | +- _Check tool permissions._ Individual connector tools can be blocked in your [connector settings](https://support.anthropic.com/en/articles/11175166-how-to-manage-and-remove-integrations-in-claude). Verify that Apify tools are set to **Always allow** or **Ask first**, not blocked. |
| 65 | +- _Check the connector version._ Claude Desktop may silently downgrade the connector to an older version. If tools aren't appearing despite the connector showing as enabled, remove and re-add the connector to trigger an update. |
| 66 | +- _Restart Claude Desktop._ Configuration changes only take effect after a restart. |
| 67 | +- _Reinstall the connector._ Remove the Apify connector and add it again. |
| 68 | + |
| 69 | +#### Authentication errors |
| 70 | + |
| 71 | +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. |
| 72 | + |
| 73 | +- _Re-authorize the connection._ Remove and re-add the Apify connector in Claude Desktop to trigger a new OAuth flow. |
| 74 | + |
| 75 | +#### Claude Desktop logs |
| 76 | + |
| 77 | +Check the Claude Desktop logs for MCP-related errors: |
| 78 | + |
| 79 | +- macOS: `~/Library/Logs/Claude/` |
| 80 | +- Linux: `~/.config/Claude/logs/` |
| 81 | +- Windows: `%APPDATA%\Claude\logs\` |
| 82 | + |
| 83 | +Look for files with `mcp` in the name for server-specific error messages. |
| 84 | + |
| 85 | +### One-click installation issues |
| 86 | + |
| 87 | +The following troubleshooting steps apply specifically to the [one-click installation](#one-click-installation) method. The remote server runs entirely on Apify's infrastructure, so there are no local logs or configuration to debug. If you experience issues with the [remote server](#remote-server-recommended), contact [Apify support](https://apify.com/contact). |
| 88 | + |
| 89 | +#### "Unable to connect to extension server" error |
| 90 | + |
| 91 | +This is the most common issue. It typically 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. |
| 92 | + |
| 93 | +1. _Consider switching to the [remote server](#remote-server-recommended) setup._ The remote server is the most reliable option. |
| 94 | +1. _Uninstall and reinstall the extension._ In Claude Desktop, disable the Apify extension, remove it, then add it again. |
| 95 | +1. _Clear the npx cache._ A stale cache can cause connection failures. Follow the steps in [Corrupted npx cache](#corrupted-npx-cache). |
| 96 | +1. _Check the [Claude Desktop logs](#claude-desktop-logs)_ for specific error messages. |
| 97 | +1. _Check your network._ Ensure your firewall or VPN is not blocking the connection. |
| 98 | +1. _Still not working?_ [Submit a GitHub issue](https://github.com/apify/apify-mcp-server/issues) or contact [Apify support](https://apify.com/contact). |
| 99 | + |
| 100 | +#### Corrupted npx cache |
| 101 | + |
| 102 | +A stale or corrupted npx cache can prevent the server from starting. Clear the cache and retry: |
| 103 | + |
| 104 | +<Tabs groupId="operating-system"> |
| 105 | +<TabItem value="macos-linux" label="macOS and Linux"> |
| 106 | + |
| 107 | +```bash |
| 108 | +rm -rf ~/.npm/_npx |
| 109 | +``` |
| 110 | + |
| 111 | +</TabItem> |
| 112 | +<TabItem value="windows" label="Windows"> |
| 113 | + |
| 114 | +```text |
| 115 | +rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx |
| 116 | +``` |
| 117 | + |
| 118 | +</TabItem> |
| 119 | +</Tabs> |
| 120 | + |
| 121 | +After clearing the cache: |
| 122 | + |
| 123 | +1. Restart Claude Desktop to re-download the server package. |
| 124 | +1. Check the [Claude Desktop logs](#claude-desktop-logs) for errors. |
| 125 | +1. If the issue persists, switch to the [remote server](#remote-server-recommended) setup, which doesn't rely on local packages. |
| 126 | + |
| 127 | +## Known limitations |
| 128 | + |
| 129 | +- Claude Desktop may silently downgrade an installed connector to an older version (for example, from 0.9.14 back to 0.9.6). This can cause tools to stop loading even though the connector still shows as enabled. Removing and re-adding the connector may prompt an update, but doesn't always resolve the issue. |
| 130 | +- Some Claude Desktop versions have inconsistent behavior with remote MCP server connections. Update to the latest version if you experience issues. |
| 131 | +- If the connector directory installation fails, use the [remote server](#remote-server-recommended) at `https://mcp.apify.com` instead. |
| 132 | + |
| 133 | +## Next steps |
| 134 | + |
| 135 | +- [Apify MCP server](/platform/integrations/mcp) - Explore tool selection, available tools, telemetry, and rate limits |
| 136 | +- [Apify MCP server configurator](https://mcp.apify.com) - Select tools visually and copy configuration |
| 137 | +- [Apify MCP server on GitHub](https://github.com/apify/apify-mcp-server) - Report bugs and suggest features |
0 commit comments