mcp-fs-server

MCP server for local filesystem operations built in Go.

• MCP stdio binary for AI clients (Claude Desktop, Cursor, MCP Inspector)
• HTTP REST API for programmatic access and the TUI
• BubbleTea TUI for interactive management
• OAuth2 / Basic auth with JWT, role-based access
• Prometheus metrics + health endpoints

Binaries

| Binary | Source | Purpose | |--------|--------|---------| | mcp-fs-server | cmd/server | HTTP API + auth + monitoring | | mcp-fs-stdio | cmd/mcp | Clean MCP stdio — for AI clients | | mcp-fs-tui | cmd/tui | BubbleTea terminal UI |

Architecture

┌──────────────────┐         ┌───────────────────────────────┐
│  mcp-fs-tui      │─────────▶  mcp-fs-server                │
│  (BubbleTea)     │  HTTP   │  ┌─────────────────────────┐  │
└──────────────────┘         │  │  REST API               │  │
                             │  │  POST /auth/login       │  │
┌──────────────────┐         │  │  GET  /api/fs/*         │  │
│  Claude Desktop  │         │  │  GET  /api/users        │  │
│  Cursor          │─────────▶  │  GET  /health /metrics  │  │
│  MCP Inspector   │  stdio  │  └─────────────────────────┘  │
│  (mcp-fs-stdio)  │         └───────────────────────────────┘
└──────────────────┘

                             ┌───────────────────────────────┐
                             │  mcp-fs-stdio                 │
                             │  (no HTTP, no stdout noise)   │
                             │  ServeStdio() only            │
                             └───────────────────────────────┘

Quick Start

1. Build

go mod tidy
make build-all

2. Start HTTP server + create first admin

./bin/mcp-fs-server \
  --config config.yaml \
  --seed-admin admin:yourpassword

--seed-admin username:password creates the user only if it doesn't exist yet. Remove the flag on subsequent starts.

3. TUI

# In a second terminal
./bin/mcp-fs-tui --server http://localhost:8080

4. MCP Inspector

make inspect
# or manually:
npx @modelcontextprotocol/inspector ./bin/mcp-fs-stdio --config config.yaml

Configuration

Default config is config.yaml. All keys can be overridden via environment variables prefixed with MCP_FS_ (dots replaced by underscores):

MCP_FS_SERVER_PORT=9090
MCP_FS_AUTH_JWT_SECRET=change-me-in-production
MCP_FS_FILESYSTEM_ROOT_PATH=/data
MCP_FS_DB_PATH=/var/lib/mcp-fs/data.db

Key options:

server:
  port: 8080

auth:
  jwt_secret: "change-me-in-production"
  access_token_ttl: "15m"

filesystem:
  root_path: "."        # sandbox root — users cannot escape this
  max_file_size: 10485760

db:
  path: "./mcp-fs.db"

OAuth2 providers

Uncomment and fill in config.yaml:

auth:
  oauth2_providers:
    - id: "github"
      name: "GitHub"
      type: "github"
      client_id: "YOUR_CLIENT_ID"
      client_secret: "YOUR_CLIENT_SECRET"
      redirect_url: "http://localhost:8080/auth/oauth2/callback/github"
      scopes: ["read:user", "user:email"]

HTTP API

Base URL: http://localhost:8080

Auth

| Method | Path | Auth | Description | |--------|------|------|-------------| | POST | /auth/login | — | Basic login → JWT | | GET | /auth/oauth2/providers | — | List OAuth2 providers | | GET | /auth/oauth2/authorize/{provider} | — | Start OAuth2 flow | | GET | /auth/oauth2/callback/{provider} | — | OAuth2 callback |

Filesystem

All endpoints require Authorization: Bearer <token>.

| Method | Path | Description | |--------|------|-------------| | GET | /api/fs/list?path=/ | List directory | | GET | /api/fs/read?path=/file.txt | Read file | | POST | /api/fs/write | Write file | | DELETE | /api/fs/delete?path=/file.txt | Delete file | | POST | /api/fs/move | Move / rename | | GET | /api/fs/search?path=/&keyword=todo | Search in files |

Users

Requires admin r

... View full README on GitHub