filesystem-mcp

A production-ready MCP (Model Context Protocol) server that gives AI agents full control over a filesystem — reading, writing, editing, searching, diffing files, executing commands, and managing processes. Built in Go with OAuth authorization and RBAC.

Features

• 🗂️ 12 powerful tools for filesystem operations, shell execution, and agent utilities
• 🔐 RBAC with JWT + CEL — restrict operations per path using glob patterns and JWT claim expressions
• ⚡ Token-efficient by design — partial file reads, batch edits, ranged diffs, search with context control
• 🔑 OAuth RFC 8414 / RFC 9728 compliant — .well-known/oauth-protected-resource and .well-known/oauth-authorization-server
• 🛡️ JWT validation — validated locally via JWKS + CEL expressions
• 🚀 Dual transport — stdio for local clients, HTTP for remote (Claude Web, OpenAI, etc.)

Tools

Filesystem

Shell & Processes

System & Utilities

RBAC

RBAC controls which operations are allowed on which filesystem paths. Rules are evaluated in order — first match wins.

Operation Categories

system_info and scratch don't touch the filesystem and are always allowed.

Configuration

rbac:
  enabled: true
  default_policy: deny # deny | allow

  rules:
    - name: "admins"
      when:
        - 'payload.groups.exists(g, g == "admin")'
      paths: ["/**"]
      operations: [read, write, exec]

    - name: "developers"
      when:
        - 'payload.groups.exists(g, g == "developer")'
      paths: ["/home/*/projects/**", "/tmp/**"]
      operations: [read, write]

    - name: "viewers"
      when:
        - 'payload.scope.contains("read")'
      paths: ["/home/*/projects/**"]
      operations: [read]

    - name: "anonymous - no JWT"
      when: []
      paths: ["/tmp/sandbox/**"]
      operations: [read]

• when — CEL expressions evaluated against the JWT payload. All must be true (AND). Empty or missing matches requests without JWT
• paths — Glob patterns. /** suffix matches everything recursively
• operations — read, write, exec
• default_policy — deny (secure by default) or allow (open, for development)

⚠️ Warning: Granting exec gives the agent full shell access. Any filesystem restrictions from paths can be bypassed via shell commands. Only grant exec to trusted identities.

Installation

From source

Requires Go 1.24+.

git clone https://github.com/achetronic/filesystem-mcp.git
cd filesystem-mcp
make build

Output: bin/filesystem-mcp-{os}-{arch}

From release binaries

Download a prebuilt binary from the Releases page. Binaries are available for linux/{386,amd64,arm64} and darwin/{amd64,arm64}.

Why no Docker image?

This MCP server is designed to control the host filesystem — reading, writing, editing files, and executing shell commands. Running it inside a container would defeat its purpose: the agent would only see the container's filesystem, not yours. Bind-mounting the entire host filesystem into a container introduces complexity and security pitfalls that are worse than just running the binary directly.

If you need network-accessible deployment (HTTP transport), run the binary as a systemd service or behind a reverse proxy. The Dockerfile and Helm chart are kept in the repo for edge cases where containerized deployment makes sense (e.g., sandboxed CI environments with specific volume mounts), but they are not the recommended way to run this.

Running

Run locally

make run

Default config starts an HTTP server on :8080. For stdio mode, modify the Makefile to use docs/config-stdio.yaml.

Client Configuration

Stdio Mode (Claude Desktop, Cursor, VSCode)

make build

// claude_desktop_config.json
{
  mcpServers: {
    filesystem: {
      command: "/path/to/bin/filesystem-mcp-linux-amd64",
      args: ["--config", "/path/to/docs/config-stdio.yaml"],
    },
  },
}

HTTP Mode (Remote clients)

npm i mcp-remote && make run

// claude_desktop_config.json
{
  mcpServers: {
    "filesystem-remote": {
      command: "npx",
      args: [
        "mcp-remote",
        "http://localhost:8080/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization: Bearer ${JWT}",
      ],
      env: {
        JWT: "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
      },
    },
  },
}

Configuration

Configuration is YAML-based, loaded via --config flag. Supports environment variable expansion ($VAR / ${VAR}).

See example configs:

• HTTP mode — Full config with JWT, RBAC, OAuth endpoints
• Stdio mode — Minimal config for local use

Documentation

• MCP Authorization Requirements
• RFC 9728 — OAuth Protected Resource Metadata
• MCP Go Library
• mcp-remote package
• CEL Specification

Contributing

All contributions are welcome!

• Open an issue to report bugs or request features
• Submit a pull request to contribute improvements

License

Licensed under the Apache 2.0 License.