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