Connect to local MCP servers changeddocs/2025-11-25/develop/connect-local-servers
Upstream edited this page at 11 Oct 2026 04:39 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 20:07 UTC.
Upstream edited
Recorded here
Lines+188added
Lines−212removed
From line
6
where the diff opens
First seen
26 Aug 2026
this site's first read of the page
Recorded edits3to this page, all time
The whole hunk
from line 6, old and new numbered
/
from line 6
66
77This guide demonstrates how to connect to local MCP servers using Claude Desktop as an example, one of the many clients that support MCP. While we focus on Claude Desktop's implementation, the concepts apply broadly to other MCP-compatible clients. By the end of this tutorial, Claude will be able to interact with files on your computer, create new documents, organize folders, and search through your file system—all with your explicit permission for each action.
88
9<Frame>
10 <img src="https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-filesystem.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=629d7e754dc358d71a408d6ce970c1b1" alt="Claude Desktop with filesystem integration showing file management capabilities" width="1732" height="2060" data-path="images/quickstart-filesystem.png" />
11</Frame>
9
1210
1311## Prerequisites
1412
from line 43
4543
4644The process involves configuring Claude Desktop to automatically start the Filesystem Server whenever you launch the application. This configuration is done through a JSON file that tells Claude Desktop which servers to run and how to connect to them.
4745
48<Steps>
49 <Step title="Open Claude Desktop Settings">
50 Start by accessing the Claude Desktop settings. Click on the Claude menu in your system's menu bar (not the settings within the Claude window itself) and select "Settings..."
46**1. Open Claude Desktop Settings**
5147
52 On macOS, this appears in the top menu bar:
48Start by accessing the Claude Desktop settings. Click on the Claude menu in your system's menu bar (not the settings within the Claude window itself) and select "Settings..."
5349
54 <Frame style={{ textAlign: "center" }}>
55 <img src="https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-menu.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=0c8b57e0e17af3624b6762a3ea944c8e" width="400" alt="Claude Desktop menu showing Settings option" data-path="images/quickstart-menu.png" />
56 </Frame>
50On macOS, this appears in the top menu bar:
5751
58 This opens the Claude Desktop configuration window, which is separate from your Claude account settings.
59 </Step>
52
6053
61 <Step title="Access Developer Settings">
62 In the Settings window, navigate to the "Developer" tab in the left sidebar. This section contains options for configuring MCP servers and other developer features.
54This opens the Claude Desktop configuration window, which is separate from your Claude account settings.
6355
64 Click the "Edit Config" button to open the configuration file:
56**2. Access Developer Settings**
6557
66 <Frame>
67 <img src="https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-developer.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=0fb595490a2f9e15c0301e771a57446c" alt="Developer settings showing Edit Config button" width="1688" height="534" data-path="images/quickstart-developer.png" />
68 </Frame>
58In the Settings window, navigate to the "Developer" tab in the left sidebar. This section contains options for configuring MCP servers and other developer features.
6959
70 This action creates a new configuration file if one doesn't exist, or opens your existing configuration. The file is located at:
60Click the "Edit Config" button to open the configuration file:
7161
72 * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
73 * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
74 </Step>
62
7563
76 <Step title="Configure the Filesystem Server">
77 Replace the contents of the configuration file with the following JSON structure. This configuration tells Claude Desktop to start the Filesystem Server with access to specific directories:
64This action creates a new configuration file if one doesn't exist, or opens your existing configuration. The file is located at:
7865
79 <CodeGroup>
80 ```json macOS theme={null}
81 {
82 "mcpServers": {
83 "filesystem": {
84 "command": "npx",
85 "args": [
86 "-y",
87 "@modelcontextprotocol/server-filesystem",
88 "/Users/username/Desktop",
89 "/Users/username/Downloads"
90 ]
91 }
92 }
93 }
94 ```
66* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
67* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
9568
96 ```json Windows theme={null}
97 {
98 "mcpServers": {
99 "filesystem": {
100 "command": "npx",
101 "args": [
102 "-y",
103 "@modelcontextprotocol/server-filesystem",
104 "C:\\Users\\username\\Desktop",
105 "C:\\Users\\username\\Downloads"
106 ]
107 }
108 }
109 }
110 ```
111 </CodeGroup>
69**3. Configure the Filesystem Server**
11270
113 Replace `username` with your actual computer username. The paths listed in the `args` array specify which directories the Filesystem Server can access. You can modify these paths or add additional directories as needed.
71Replace the contents of the configuration file with the following JSON structure. This configuration tells Claude Desktop to start the Filesystem Server with access to specific directories:
11472
115 <Tip>
116 **Understanding the Configuration**
73```json macOS theme={null}
74{
75 "mcpServers": {
76 "filesystem": {
77 "command": "npx",
78 "args": [
79 "-y",
80 "@modelcontextprotocol/server-filesystem",
81 "/Users/username/Desktop",
82 "/Users/username/Downloads"
83 ]
84 }
85 }
86}
87```
11788
118 * `"filesystem"`: A friendly name for the server that appears in Claude Desktop
119 * `"command": "npx"`: Uses Node.js's npx tool to run the server
120 * `"-y"`: Automatically confirms the installation of the server package
121 * `"@modelcontextprotocol/server-filesystem"`: The package name of the Filesystem Server
122 * The remaining arguments: Directories the server is allowed to access
123 </Tip>
89```json Windows theme={null}
90{
91 "mcpServers": {
92 "filesystem": {
93 "command": "npx",
94 "args": [
95 "-y",
96 "@modelcontextprotocol/server-filesystem",
97 "C:\\Users\\username\\Desktop",
98 "C:\\Users\\username\\Downloads"
99 ]
100 }
101 }
102}
103```
124104
125 <Warning>
126 **Security Consideration**
105Replace `username` with your actual computer username. The paths listed in the `args` array specify which directories the Filesystem Server can access. You can modify these paths or add additional directories as needed.
127106
128 Only grant access to directories you're comfortable with Claude reading and modifying. The server runs with your user account permissions, so it can perform any file operations you can perform manually.
129 </Warning>
130 </Step>
107> [!TIP]
108>
109> **Understanding the Configuration**
110>
111> * `"filesystem"`: A friendly name for the server that appears in Claude Desktop
112> * `"command": "npx"`: Uses Node.js's npx tool to run the server
113> * `"-y"`: Automatically confirms the installation of the server package
114> * `"@modelcontextprotocol/server-filesystem"`: The package name of the Filesystem Server
115> * The remaining arguments: Directories the server is allowed to access
131116
132 <Step title="Restart Claude Desktop">
133 After saving the configuration file, completely quit Claude Desktop and restart it. The application needs to restart to load the new configuration and start the MCP server.
117> [!WARNING]
118>
119> **Security Consideration**
120>
121> Only grant access to directories you're comfortable with Claude reading and modifying. The server runs with your user account permissions, so it can perform any file operations you can perform manually.
134122
135 Upon successful restart, click the "Add files, connectors and more" indicator <img src="https://mintcdn.com/mcp/cpXzQjUOzyH0mCNH/images/claude-add-files-connectors-and-more.png?fit=max&auto=format&n=cpXzQjUOzyH0mCNH&q=85&s=53acf21f6807dd5323b70b84b5d98d8a" style={{display: 'inline', margin: 0, height: '1.3em'}} width="33" height="33" data-path="images/claude-add-files-connectors-and-more.png" /> in the bottom-left corner of the conversation input box:
123**4. Restart Claude Desktop**
136124
137 <Frame>
138 <img src="https://mintcdn.com/mcp/akpggzunDlIcY2im/images/quickstart-slider.png?fit=max&auto=format&n=akpggzunDlIcY2im&q=85&s=a1ebd4259cff2a7472171885f2edc035" alt="Claude Desktop interface showing MCP server indicator" width="1414" height="410" data-path="images/quickstart-slider.png" />
139 </Frame>
125After saving the configuration file, completely quit Claude Desktop and restart it. The application needs to restart to load the new configuration and start the MCP server.
140126
141 Click on this indicator, then scroll over "Connectors" and click "Manage connectors". Select "filesystem" from the connector list to view the the Filesystem Server's available tools:
127Upon successful restart, click the "Add files, connectors and more" indicator  in the bottom-left corner of the conversation input box:
142128
143 <Frame style={{ textAlign: "center" }}>
144 <img src="https://mintcdn.com/mcp/cpXzQjUOzyH0mCNH/images/quickstart-tools.png?fit=max&auto=format&n=cpXzQjUOzyH0mCNH&q=85&s=212a63d76daba170d52db0d2f6f582be" width="400" alt="Available filesystem tools in Claude Desktop" data-path="images/quickstart-tools.png" />
145 </Frame>
129
146130
147 If the Filesystem Server doesn't connect, refer to the [Troubleshooting](#troubleshooting) section for debugging steps.
148 </Step>
149</Steps>
131Click on this indicator, then scroll over "Connectors" and click "Manage connectors". Select "filesystem" from the connector list to view the the Filesystem Server's available tools:
150132
133
134
135If the Filesystem Server doesn't connect, refer to the [Troubleshooting](#troubleshooting) section for debugging steps.
136
151137## Using the Filesystem Server
152138
153139With the Filesystem Server connected, Claude can now interact with your file system. Try these example requests to explore the capabilities:
from line 148
162148
163149Before executing any file system operation, Claude will request your approval. This ensures you maintain control over all actions:
164150
165<Frame style={{ textAlign: "center" }}>
166 <img src="https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-approve.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=98cc6e9dfe885fbd6e9bfae40601e494" width="500" alt="Claude requesting approval to perform a file operation" data-path="images/quickstart-approve.png" />
167</Frame>
151
168152
169153Review each request carefully before approving. You can always deny a request if you're not comfortable with the proposed action.
170154
from line 156
172156
173157If you encounter issues setting up or using the Filesystem Server, these solutions address common problems:
174158
175<AccordionGroup>
176 <Accordion title="Server not showing up in Claude / hammer icon missing">
177 1. Restart Claude Desktop completely
178 2. Check your `claude_desktop_config.json` file syntax
179 3. Make sure the file paths included in `claude_desktop_config.json` are valid and that they are absolute and not relative
180 4. Look at [logs](#getting-logs-from-claude-for-desktop) to see why the server is not connecting
181 5. In your command line, try manually running the server (replacing `username` as you did in `claude_desktop_config.json`) to see if you get any errors:
159> **Server not showing up in Claude / hammer icon missing**
160>
161> 1. Restart Claude Desktop completely
162> 2. Check your `claude_desktop_config.json` file syntax
163> 3. Make sure the file paths included in `claude_desktop_config.json` are valid and that they are absolute and not relative
164> 4. Look at [logs](#getting-logs-from-claude-for-desktop) to see why the server is not connecting
165> 5. In your command line, try manually running the server (replacing `username` as you did in `claude_desktop_config.json`) to see if you get any errors:
166>
167> ```bash macOS/Linux theme={null}
168> npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads
169> ```
170>
171> ```powershell Windows theme={null}
172> npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads
173> ```
182174
183 <CodeGroup>
184 ```bash macOS/Linux theme={null}
185 npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads
186 ```
175> **Getting logs from Claude Desktop**
176>
177> Claude.app logging related to MCP is written to log files in:
178>
179> * macOS: `~/Library/Logs/Claude`
180>
181> * Windows: `%APPDATA%\Claude\logs`
182>
183> * `mcp.log` will contain general logging about MCP connections and connection failures.
184>
185> * Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.
186>
187> You can run the following command to list recent logs and follow along with any new ones (on Windows, it will only show recent logs):
188>
189> ```bash macOS/Linux theme={null}
190> tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
191> ```
192>
193> ```powershell Windows theme={null}
194> type "%APPDATA%\Claude\logs\mcp*.log"
195> ```
187196
188 ```powershell Windows theme={null}
189 npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads
190 ```
191 </CodeGroup>
192 </Accordion>
197> **Tool calls failing silently**
198>
199> If Claude attempts to use the tools but they fail:
200>
201> 1. Check Claude's logs for errors
202> 2. Verify your server builds and runs without errors
203> 3. Try restarting Claude Desktop
193204
194 <Accordion title="Getting logs from Claude Desktop">
195 Claude.app logging related to MCP is written to log files in:
205> **None of this is working. What do I do?**
206>
207> Please refer to our [debugging guide](/docs/2025-11-25/tools/debugging) for better debugging tools and more detailed guidance.
196208
197 * macOS: `~/Library/Logs/Claude`
209> **ENOENT error and `$\{APPDATA\}` in paths on Windows**
210>
211> If your configured server fails to load, and you see within its logs an error referring to `${APPDATA}` within a path, you may need to add the expanded value of `%APPDATA%` to your `env` key in `claude_desktop_config.json`:
212>
213> ```json theme={null}
214> {
215> "brave-search": {
216> "command": "npx",
217> "args": ["-y", "@modelcontextprotocol/server-brave-search"],
218> "env": {
219> "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
220> "BRAVE_API_KEY": "..."
221> }
222> }
223> }
224> ```
225>
226> With this change in place, launch Claude Desktop once again.
227>
228> > [!WARNING]
229> >
230> > **npm should be installed globally**
231> >
232> > The `npx` command may continue to fail if you have not installed npm globally. If npm is already installed globally, you will find `%APPDATA%\npm` exists on your system. If not, you can install npm globally by running the following command:
233> >
234> > ```bash theme={null}
235> > npm install -g npm
236> > ```
198237
199 * Windows: `%APPDATA%\Claude\logs`
200
201 * `mcp.log` will contain general logging about MCP connections and connection failures.
202
203 * Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.
204
205 You can run the following command to list recent logs and follow along with any new ones (on Windows, it will only show recent logs):
206
207 <CodeGroup>
208 ```bash macOS/Linux theme={null}
209 tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
210 ```
211
212 ```powershell Windows theme={null}
213 type "%APPDATA%\Claude\logs\mcp*.log"
214 ```
215 </CodeGroup>
216 </Accordion>
217
218 <Accordion title="Tool calls failing silently">
219 If Claude attempts to use the tools but they fail:
220
221 1. Check Claude's logs for errors
222 2. Verify your server builds and runs without errors
223 3. Try restarting Claude Desktop
224 </Accordion>
225
226 <Accordion title="None of this is working. What do I do?">
227 Please refer to our [debugging guide](/docs/2025-11-25/tools/debugging) for better debugging tools and more detailed guidance.
228 </Accordion>
229
230 <Accordion title="ENOENT error and `${APPDATA}` in paths on Windows">
231 If your configured server fails to load, and you see within its logs an error referring to `${APPDATA}` within a path, you may need to add the expanded value of `%APPDATA%` to your `env` key in `claude_desktop_config.json`:
232
233 ```json theme={null}
234 {
235 "brave-search": {
236 "command": "npx",
237 "args": ["-y", "@modelcontextprotocol/server-brave-search"],
238 "env": {
239 "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
240 "BRAVE_API_KEY": "..."
241 }
242 }
243 }
244 ```
245
246 With this change in place, launch Claude Desktop once again.
247
248 <Warning>
249 **npm should be installed globally**
250
251 The `npx` command may continue to fail if you have not installed npm globally. If npm is already installed globally, you will find `%APPDATA%\npm` exists on your system. If not, you can install npm globally by running the following command:
252
253 ```bash theme={null}
254 npm install -g npm
255 ```
256 </Warning>
257 </Accordion>
258</AccordionGroup>
259
260238## Next Steps
261239
262240Now that you've successfully connected Claude Desktop to a local MCP server, explore these options to expand your setup:
263241
264<CardGroup cols={2}>
265 <Card title="Explore other servers" icon="grid" href="https://github.com/modelcontextprotocol/servers">
266 Browse our collection of official and community-created MCP servers for
267 additional capabilities
268 </Card>
242> **[Explore other servers](https://github.com/modelcontextprotocol/servers)**
243>
244> Browse our collection of official and community-created MCP servers for
245> additional capabilities
269246
270 <Card title="Build your own server" icon="code" href="/docs/2025-11-25/develop/build-server">
271 Create custom MCP servers tailored to your specific workflows and
272 integrations
273 </Card>
247> **[Build your own server](/docs/2025-11-25/develop/build-server)**
248>
249> Create custom MCP servers tailored to your specific workflows and
250> integrations
274251
275 <Card title="Connect to remote servers" icon="cloud" href="/docs/2025-11-25/develop/connect-remote-servers">
276 Learn how to connect Claude to remote MCP servers for cloud-based tools and
277 services
278 </Card>
252> **[Connect to remote servers](/docs/2025-11-25/develop/connect-remote-servers)**
253>
254> Learn how to connect Claude to remote MCP servers for cloud-based tools and
255> services
279256
280 <Card title="Understand the protocol" icon="book" href="/docs/2025-11-25/learn/architecture">
281 Dive deeper into how MCP works and its architecture
282 </Card>
283</CardGroup>
257> **[Understand the protocol](/docs/2025-11-25/learn/architecture)**
258>
259> Dive deeper into how MCP works and its architecture
284260
No line in this hunk matches that.