Filesystem MCP server in Zed context servers, configured in settings.json.
Zed calls MCP servers context servers and configures them in its main settings.json. Here's the exact entry for mcp-server-filesystem, plus how to confirm Zed's agent can actually see the tools.
mcp-server-filesystem gives Zed's agent read, write, and search access to local files outside whatever project you have open. It's an npm-packaged MCP server developed in the ByteDance UI-TARS repo (github.com/bytedance/ui-tars-desktop, 36.3k stars), and it runs over stdio — exactly what Zed expects from a locally launched server.
Unlike clients with a dedicated MCP file, Zed folds MCP configuration into its main settings: a context_servers object in ~/.config/zed/settings.json. Run the Zed: Open Settings action and you're in the right file.
Add a context_servers entry
Open settings.json (Cmd-, or the Zed: Open Settings action) and add a context_servers block alongside your existing settings — don't replace the file. The final argument is the directory the server is permitted to operate on; replace the example path with yours, and see the UI-TARS repo README for any further flags the current release supports.
{
"context_servers": {
"filesystem": {
"source": "custom",
"command": "npx",
"args": ["-y", "mcp-server-filesystem", "/Users/you/projects"],
"env": {}
}
}
}Confirm it in the Agent Panel
Open the Agent Panel and check its settings view — configured context servers are listed there with a running/error indicator. If the entry shows as running, start a conversation and ask the agent to list files in the exposed directory; you should see it call the filesystem tools rather than answer from memory.
Zed applies settings.json changes live, but the assistant panel sometimes holds onto an older server list — closing and reopening the panel, or restarting Zed, forces a clean reconnect.
Why pair Zed with a filesystem server
Zed's agent works within your open worktrees. The MCP server is for everything else: reference docs in another directory, a sibling repo you don't want as a second worktree, an output folder for generated files. Because you control the directory argument, you decide exactly how far beyond the project the agent can reach — one folder or your whole projects tree.
Troubleshooting in Zed
If the server shows an error state in the Agent Panel, pull up Zed's log with the Zed: Open Log action — server launch failures (npx not found, package install errors, a directory argument that doesn't exist) are recorded there with the underlying stderr.
Config-shape mistakes are the other common cause. The block is context_servers, not mcpServers — entries under the wrong key are ignored without complaint. And since this all lives in your main settings.json, a JSON syntax error anywhere in the file can break more than just MCP; Zed will flag the parse error in the editor when you open the file. macOS PATH issues apply here too: if npx resolves in your terminal but not in Zed, write the absolute npx path into the command field.
The live listing
The server's Loomal marketplace listing at https://loomal.ai/marketplace/mcp-server-filesystem shows its live-probed tool list, so you know what Zed's agent will get before you touch settings.json. Maintainers can claim their server's listing to verify ownership and price calls for agent consumers.
FAQ
How do I install the Filesystem server in Zed?
Add a context_servers entry to ~/.config/zed/settings.json with command npx and args ["-y", "mcp-server-filesystem", "<directory>"], then reopen the Agent Panel. Zed launches the server over stdio and lists its tools in the panel's settings view.
Where is Zed's MCP config file?
There's no separate MCP file — Zed configures context servers inside its main settings file at ~/.config/zed/settings.json, under the context_servers key. The Zed: Open Settings action takes you straight there.
The server is configured but the agent never uses it — why?
First confirm it's under context_servers (Zed ignores an mcpServers key) and shows as running in the Agent Panel. If it's errored, check Zed: Open Log for the launch failure — most often npx isn't on Zed's PATH or the directory argument doesn't exist. Restart the panel after fixing.
Can I limit the agent to read-only access?
The directory argument controls where the server can operate, not what operations exist — write tools are part of the server. Keep the exposed path narrow, and review the agent's proposed tool calls in the panel before approving anything destructive.
Browse more MCP servers for Zed.
Compare tool lists before you edit settings.json.