Skip to content

Commit ad96f3a

Browse files
marcel-rbroclaude
marcel-rbro
and
claude
committed
docs: add Claude Desktop setup and troubleshooting page for Apify MCP
Add a dedicated page for Claude Desktop users covering three setup methods (one-click .mcpb, remote server, local stdio), troubleshooting common issues, and known limitations. Cross-reference from the main MCP page. Closes #2368 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 1a30ebe commit ad96f3a

File tree

2 files changed

+202
-0
lines changed

2 files changed

+202
-0
lines changed

‎sources/platform/integrations/ai/claude-desktop.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
title: Claude Desktop integration
3+
sidebar_label: Claude Desktop
4+
description: Set up the Apify MCP server in Claude Desktop with remote or local configuration, and troubleshoot common connection issues.
5+
sidebar_position: 1.5
6+
slug: /integrations/claude-desktop
7+
---
8+
9+
import Tabs from '@theme/Tabs';
10+
import TabItem from '@theme/TabItem';
11+
12+
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.
13+
14+
## Prerequisites
15+
16+
- An [Apify account](https://console.apify.com/sign-up) with an [API token](https://console.apify.com/account#/integrations)
17+
- [Claude Desktop](https://claude.ai/download) installed
18+
- [Node.js](https://nodejs.org/) version 18 or higher (only required for [local stdio setup](#local-stdio-server))
19+
20+
## Connect to Apify
21+
22+
Choose one of the following methods, from simplest to most flexible.
23+
24+
### One-click installation (recommended)
25+
26+
Download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb). Claude Desktop automatically registers the Apify MCP server and prompts you to approve the connection.
27+
28+
:::caution Connector directory
29+
30+
If you found Apify through the Claude Desktop connector directory, the automatic install may fail silently or show an "Unable to connect to extension server" error. Use the `.mcpb` file above or the [manual configuration](#remote-server-manual-configuration) below instead.
31+
32+
:::
33+
34+
### Remote server (manual configuration)
35+
36+
The remote server at `https://mcp.apify.com` is the simplest manual setup - no local dependencies required.
37+
38+
1. Open Claude Desktop.
39+
1. Go to **Settings** > **Developer** > **Edit Config**.
40+
1. Add the Apify MCP server configuration:
41+
42+
<Tabs>
43+
<TabItem value="OAuth" label="OAuth (recommended)">
44+
45+
```json
46+
{
47+
"mcpServers": {
48+
"apify": {
49+
"url": "https://mcp.apify.com"
50+
}
51+
}
52+
}
53+
```
54+
55+
On first connection, your browser opens to sign in to Apify and authorize the connection. This OAuth flow keeps your API token secure.
56+
57+
</TabItem>
58+
<TabItem value="Bearer token" label="Bearer token">
59+
60+
```json
61+
{
62+
"mcpServers": {
63+
"apify": {
64+
"url": "https://mcp.apify.com",
65+
"headers": {
66+
"Authorization": "Bearer <APIFY_TOKEN>"
67+
}
68+
}
69+
}
70+
}
71+
```
72+
73+
Replace `<APIFY_TOKEN>` with your API token from the [Integrations section](https://console.apify.com/account#/integrations) in Apify Console.
74+
75+
</TabItem>
76+
</Tabs>
77+
78+
:::note Older Claude Desktop versions
79+
80+
If your version of Claude Desktop does not support the `url` field, use the `mcp-remote` bridge package:
81+
82+
```json
83+
{
84+
"mcpServers": {
85+
"apify": {
86+
"command": "npx",
87+
"args": ["-y", "mcp-remote", "https://mcp.apify.com/sse"]
88+
}
89+
}
90+
}
91+
```
92+
93+
This requires Node.js version 18 or higher.
94+
95+
:::
96+
97+
### Local stdio server
98+
99+
Run the MCP server locally for development, testing, or when you need offline access. This method requires Node.js.
100+
101+
1. Open Claude Desktop.
102+
1. Go to **Settings** > **Developer** > **Edit Config**.
103+
1. Add the following configuration:
104+
105+
```json
106+
{
107+
"mcpServers": {
108+
"actors-mcp-server": {
109+
"command": "npx",
110+
"args": ["-y", "@apify/actors-mcp-server"],
111+
"env": {
112+
"APIFY_TOKEN": "<APIFY_TOKEN>"
113+
}
114+
}
115+
}
116+
}
117+
```
118+
119+
Replace `<APIFY_TOKEN>` with your API token from the [Integrations section](https://console.apify.com/account#/integrations) in Apify Console.
120+
121+
:::info Output schema inference
122+
123+
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.
124+
125+
:::
126+
127+
## Verify the connection
128+
129+
1. Restart Claude Desktop after saving configuration changes.
130+
1. Open a new conversation.
131+
1. Look for the hammer icon in the chat input area - this indicates MCP tools are available.
132+
1. Click the hammer icon to confirm Apify tools appear in the list.
133+
1. Test with a prompt like: "Search for web scraping Actors on Apify."
134+
135+
## Troubleshooting
136+
137+
### Tools not loading
138+
139+
- **Restart Claude Desktop.** Configuration changes only take effect after a restart.
140+
- **Check the config file location.** Verify you edited the correct file:
141+
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
142+
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
143+
- **Validate JSON syntax.** Ensure there are no trailing commas, missing quotes, or mismatched brackets. Paste your config into a JSON validator if needed.
144+
145+
### "Unable to connect" error
146+
147+
- **Verify the server URL.** For remote setup, use exactly `https://mcp.apify.com` with no trailing slash.
148+
- **Check your network.** Ensure your firewall or VPN is not blocking the connection.
149+
- **For local stdio setup:** Confirm Node.js version 18 or higher is installed by running `node -v` in your terminal.
150+
- **Try the remote server.** If the local server fails, switch to the [remote server configuration](#remote-server-manual-configuration) to rule out local environment issues.
151+
152+
### Corrupted npx cache
153+
154+
A stale or corrupted npx cache can prevent the local server from starting. Clear the cache and retry:
155+
156+
- macOS and Linux:
157+
158+
```bash
159+
rm -rf ~/.npm/_npx
160+
```
161+
162+
- Windows:
163+
164+
```bash
165+
rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx
166+
```
167+
168+
After clearing the cache, restart Claude Desktop to re-download the server package.
169+
170+
### Authentication errors
171+
172+
- **Check your API token.** Verify the token in the [Integrations section](https://console.apify.com/account#/integrations) of Apify Console.
173+
- **For local stdio setup:** Ensure the `APIFY_TOKEN` environment variable is set correctly in your config file.
174+
- **For remote OAuth:** Remove and re-add the Apify MCP server in Claude Desktop to re-authorize.
175+
176+
### Check Claude Desktop logs
177+
178+
If the above steps don't resolve your issue, check the Claude Desktop logs for MCP-related errors:
179+
180+
- macOS: `~/Library/Logs/Claude/`
181+
- Linux: `~/.config/Claude/logs/`
182+
- Windows: `%APPDATA%\Claude\logs\`
183+
184+
Look for files with `mcp` in the name for server-specific error messages.
185+
186+
## Known limitations
187+
188+
- **Connector directory:** 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.
189+
- **Cowork mode:** Multi-agent cowork mode may not pass MCP tool results between agents reliably when using the local stdio server.
190+
- **Transport inconsistencies:** Some Claude Desktop versions have inconsistent behavior with remote MCP server connections. Update to the latest version if you experience issues.
191+
192+
## Next steps
193+
194+
- [Apify MCP server](/integrations/mcp) - Explore tool selection, available tools, telemetry, and rate limits
195+
- [Apify MCP server configurator](https://mcp.apify.com) - Select tools visually and copy configuration
196+
- [Apify MCP server on GitHub](https://github.com/apify/apify-mcp-server) - Report bugs and suggest features

‎sources/platform/integrations/ai/mcp.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,8 @@ To manually configure Apify's MCP server for Claude Desktop:
233233

234234
Replace `<APIFY_TOKEN>` with your actual Apify API token from the [Integrations section](https://console.apify.com/account#/integrations).
235235

236+
For detailed setup options and troubleshooting, see the [Claude Desktop integration guide](/integrations/claude-desktop).
237+
236238
</TabItem>
237239
</Tabs>
238240

@@ -431,6 +433,10 @@ documentation queries. If you exceed this limit, you'll receive a `429` response
431433
<!-- markdownlint-disable MD001 -->
432434
## Troubleshooting
433435

436+
:::tip Claude Desktop issues
437+
For Claude Desktop-specific troubleshooting (tools not loading, connection errors, corrupted cache), see [Claude Desktop troubleshooting](/integrations/claude-desktop#troubleshooting).
438+
:::
439+
434440
##### Authentication errors
435441

436442
- _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.

0 commit comments

Comments
 (0)