MCP Servers

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 — delegated to external proxies (Istio) or validated locally via JWKS + CEL
• 🚀 Dual transport — stdio for local clients, HTTP for remote (Claude Web, OpenAI, etc.)

Tools

Filesystem

| Tool | Description | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | ls | List directory contents with depth, glob filter, hidden file toggle. depth=1 is flat, depth=N is tree | | read_file | Read a file fully or specific line ranges. Accepts an array of {offset, limit} ranges for partial reads | | write_file | Create or overwrite a file. Auto-creates parent directories. Saves undo state | | edit_file | Batch find-and-replace on a file. Accepts an array of {old_text, new_text, replace_all} edits applied sequentially. Reports successes and failures | | search | Recursive grep with regex or literal mode. Configurable include/exclude patterns, context lines, max results | | diff | Unified diff between two files or sections. Supports line ranges on both sides |

Shell & Processes

| Tool | Description | | ---------------- | -------------------------------------------------------------------------------------- | | exec | Execute shell commands in foreground (with timeout) or background (returns process ID) | | process_status | Get output and status of a background process, or list all background processes | | process_kill | Kill a background process |

System & Utilities

| Tool | Description | | ------------- | ------------------------------------------------------------------------------------- | | system_info | OS, architecture, hostname, user, working directory, shell, PATH | | undo | Revert a file to its state before the last write_file or edit_file | | scratch | In-memory key-value store for the agent to save/retrieve temporary data between calls |

RBAC

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

Operation Categories

| Category | Tools | Notes | | -------- | ---------------------------------- | ---------------------------------------------------------------------- | | read | ls, read_file, search, diff | Safe, read-only operations | | write | write_file, edit_file, undo | Modifies files | | exec | exec, process_status, process_kill | Full shell access — granting this bypasses filesystem restrictions |

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}",
        "--header",
        "X-Validated-Jwt: ${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.