basic-fns-mcp

A streamable-HTTP/stdio MCP server exposing the core filesystem, shell, search, and listing tools that mirror the default agent toolset.

Tools

All filesystem paths are resolved relative to the configured server root. The server refuses any path that resolves outside that root, including symlinks that escape it.

Related MCP server: File Operations MCP Server

Quick start

Install and run over HTTP:

uv sync
uv run basic-fns-mcp --root . --port 8080

Add it to Claude Code:

claude mcp add --transport http basic-fns http://127.0.0.1:8080/mcp

stdio

The same server runs over stdio, where the client spawns it as a subprocess:

uv run basic-fns-mcp --stdio            # or: --transport stdio

Add it to Claude Code:

claude mcp add basic-fns -- uv run --directory /path/to/basic-fns-mcp basic-fns-mcp --stdio

Or in an MCP client config file:

{
  "mcpServers": {
    "basic-fns": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/basic-fns-mcp", "basic-fns-mcp", "--stdio"],
      "env": { "BASIC_FNS_ROOT": "/path/to/your/project" }
    }
  }
}

On stdio, stdout is the protocol channel — the startup banner is suppressed and all logging goes to stderr. The --host/--port flags are ignored.

The module can also be served directly, since tools are registered at import time:

uv run fastmcp run src/basic_fns_mcp/server.py

CLI flags / environment variables

Command-line arguments win over environment variables.

Security

• Path sandbox: read, write, edit, grep, find, and ls resolve every path inside --root. Symlinks are followed and checked; any path that resolves outside the root is rejected.

• bash is not sandboxed: bash runs with the full privileges of the server process. A shell command can cd anywhere, read any file the server user can read, and execute arbitrary code. Only bind to loopback (127.0.0.1) and expose this server to trusted clients.

• No command blocklist: Blocklists are easily bypassed and create a false sense of security, so none is implemented.

• Read-only mode: Use --read-only to prevent file modification via this server.

Development

Run the test suite:

uv run pytest -q

License

MIT