fs-mcp

A tiny MCP server exposing six tools:

1. explore_filesystem(subpath?, glob?) — lists files/folders under the root directory, optionally filtered by a glob (**/*.js, etc).
2. edit_file(path, edits[], createIfMissing?) — applies git-style line edits (replace / insert / delete a line range) to a file under the root.
3. create_file(path, content?, overwrite?) — creates a new file with optional content, creating parent directories as needed.
4. delete_file(path, recursive?) — deletes a file or directory under the root (optionally recursive for non-empty directories).
5. read_file(path, startLine?, endLine?) — reads file content, optionally scoped to a line range, with line numbers prefixed.
6. grep(pattern, glob?, useRegex?, caseInsensitive?) — searches for text patterns in files, with optional regex support and glob filtering.

Root = wherever the process's working directory is when it starts.

Install as a global CLI

npm install
npm link          # or: npm install -g .

This gives you a global fs-mcp command (wired up via the bin field in package.json).

Running it

fs-mcp                 # stdio mode (default) — for Claude Desktop/Code,
                        # which spawn the process themselves
fs-mcp --http          # HTTP mode on http://localhost:4823/mcp — for
                        # curl, the MCP Inspector, or the on-demand
                        # Claude Desktop setup below
fs-mcp --http -p 5000   # custom port
fs-mcp --help

Whichever folder you're standing in when you run it becomes the exposed root.

Connecting to Claude Desktop

Claude Desktop spawns MCP servers itself and talks over stdio — it does not inherit your terminal's current directory. That gives you two setup options depending on how you want to work:

Option A — on-demand from any folder (recommended if you want the CLI feel)

Configure Desktop once, pointed at a fixed local port rather than a fixed folder. See claude_desktop_config.example.json — merge its "fs-mcp" entry into your existing mcpServers object at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop once. From then on:

cd ~/whatever/project
fs-mcp --http

That folder is now what Claude can see, for as long as the server is running. Ctrl+C it and start it again from a different folder to switch context — no further Desktop config changes needed.

Note: --allow-http is required because mcp-remote (the stdio↔HTTP bridge) defaults to expecting HTTPS + OAuth for real remote servers; this flag tells it plain unauthenticated localhost traffic is fine.

Option B — one fixed folder, always available

If you'd rather Desktop always expose the same project without having to manually start anything:

{
  "mcpServers": {
    "fs-mcp": {
      "command": "fs-mcp",
      "cwd": "/absolute/path/to/the/folder/you/want/exposed"
    }
  }
}

Restart Desktop. This uses stdio mode directly — no proxy, no manual fs-mcp --http step — but changing the exposed folder means editing this config and restarting Desktop again.

Security notes

• Every path is resolved against the root and rejected if it would escape it (e.g. ../../etc/passwd) — verified with a path-traversal test.
• There's no authentication. Anything that can reach the server (any local process, in --http mode) can read and write any file under the root. Fine for trusted local dev use; don't run it somewhere sensitive, and don't bind it beyond localhost.

Edit semantics (edit_file)

Edits are {startLine, endLine, newLines}, 1-indexed and inclusive:

• Replace lines 3–5: {startLine: 3, endLine: 5, newLines: ["new content"]}
• Delete lines 3–5: {startLine: 3, endLine: 5, newLines: []}
• Insert before line 6 (no deletion): {startLine: 6, endLine: 5, newLines: ["inserted"]}

Multiple edits in one call are applied bottom-to-top internally, so line numbers in your edit list don't shift as earlier edits are applied.