FileBridge MCP

Give Claude direct access to your project files - securely, from anywhere.

FileBridge MCP is an open-source Model Context Protocol (MCP) server that connects Claude.ai to your server's files and commands. Once connected, Claude can read, write, search, manage files, and run pre-approved shell commands - directly from the browser.

Works with: claude.ai (browser) · Claude Code · Claude Desktop · Anthropic API

Why FileBridge MCP?

Claude is a great developer assistant, but without file access it can only work with what you paste into the chat. FileBridge MCP closes that gap:

• Read & edit files - Claude can open any file in your project, make changes, and save them back
• Search across your codebase - find where a function is used, what imports a module, where a string appears
• Understand your project structure - Claude sees the full folder tree, not just isolated snippets
• Run approved commands - let Claude run npm test, git pull, pm2 restart, and more - only what you whitelist
• Multiple workspaces - give Claude access to several project directories at once with a single token
• Stays sandboxed - Claude can only access the folders you define. Nothing else is reachable
• No vendor lock-in - standard MCP protocol, works with any MCP-compatible AI client

How It Works

claude.ai (browser)
      │  HTTPS + Bearer token
      ▼
┌─────────────────────────────────┐
│         FileBridge MCP          │  Node.js / Express
│                                 │
│  Auth middleware                │  → rejects bad/missing tokens
│  Path guard                     │  → blocks path traversal
│  Tools:                         │
│    read_file                    │
│    write_file                   │
│    list_files                   │
│    delete_file                  │
│    search_in_files              │
│    replace_in_files             │
│    get_project_structure        │
│    list_workspaces              │  ← multi-workspace support
│    run_command                  │  ← whitelisted shell commands
│    list_allowed_commands        │
└──────────┬──────────────────────┘
           │ fs.* / child_process
           ▼
   /your/base/path/   ← sandboxed folders only
   /your/workspace-2/

Quick Start

1 - Install

git clone https://github.com/your-username/filebridge-mcp.git
cd filebridge-mcp
npm install

2 - Configure

cp .env.example .env
nano .env

PORT=3000
BASE_PATH=/absolute/path/to/your/project
BEARER_TOKEN=<generate below>

Generate a strong token:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

3 - Run

# Production (stays alive across reboots)
npm install -g pm2
pm2 start src/server.js --name filebridge-mcp
pm2 save && pm2 startup

# Development (auto-restarts on changes)
npm run dev

Deploy to a VPS (required for claude.ai)

Claude.ai connects to your MCP server from Anthropic's cloud infrastructure - so the server must be reachable over public HTTPS. A simple nginx + Let's Encrypt setup handles this for free.

nginx config

sudo apt install nginx certbot python3-certbot-nginx -y
sudo nano /etc/nginx/sites-available/filebridge-mcp

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass         http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header   Host $host;
        proxy_buffering    off;       # required for SSE streaming
        proxy_cache        off;
        proxy_read_timeout 86400s;   # keep SSE connections alive
    }
}

sudo ln -s /etc/nginx/sites-available/filebridge-mcp /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d your-domain.com

Verify:

curl https://your-domain.com/health
# → {"status":"ok","basePath":"/your/base/path"}

Connect to Claude.ai

1. Open claude.ai → Settings → Connectors → Add custom connector
2. Fill in the form:

| Field | Value | |---|---| | Name | FileBridge MCP | | Remote MCP server URL | https://your-domain.com/sse?token=YOUR_BEARER_TOKEN | | OAuth Client ID | (leave empty) | | OAuth Client Secret | (leave empty) |

3. Click Add ✓

Why the token is in the URL: The claude.ai connector form only supports OAuth fields - there is no custom header field. Passing the token as ?token= over HTTPS is safe because the connection is fully encrypted. The server also accepts Authorization: Bearer headers for Claude Code and API usage.

Connect via Claude Code or API

{
  "mcpServers": {
    "filebridge": {
      "url": "https://your-domain.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_BEARER_TOKEN"
      }
    }
  }
}

Available Tools

| Tool | What it does | |---|---| | read_file(file_path) | Read any file's contents | | write_file(file_path, content) | Create or overwrite a file | | list_files(directory_path) | List files and folders at a path | | delete_file(file_path) | Delete a file | | get_project_structure() | Full visual tree of your project | | search_in_files(keyword) | Grep-style search with line numbers | | replace_in_files(search, replace) | Find and replace across files | | list_workspaces() | Show all accessible workspaces | | run_command(command) | Run a whitelisted shell command | | list_allowed_commands() | Show all permitted commands |

Multi-Workspace Support

Give Claude access to multiple directories with a single token. Each workspace has a short name and a directory path.

Configure in .env

# Comma-separated "name:/absolute/path" pairs
WORKSPACES=frontend:/var/www/frontend,backend:/var/www/backend,docs:/var/www/docs

Or in config.json

{
  "workspaces": {
    "frontend": "/var/www/frontend",
    "backend":  "/var/www/backend",
    "docs":     "/var/www/docs"
  }
}

How to use

In any file tool, prefix the path with the workspace name and a colon:

read_file("backend:src/index.js")
write_file("frontend:app/page.tsx", "...")
list_files("docs:")

Paths without a prefix always resolve against the default BASE_PATH. Claude can call list_workspaces to discover what's available.

Allowed Commands

Let Claude run pre-approved shell commands on your server - tests, deploys, restarts, git operations. Only the exact strings you whitelist can be executed.

Configure in .env

# Comma-separated exact command strings
ALLOWED_COMMANDS=npm test,git pull,git status,pm2 restart all,pm2 status,df -h

Or in config.json

{
  "allowedCommands": ["npm test", "git pull", "git status", "pm2 restart all"],
  "commandTimeoutMs": 30000
}

If allowedCommands is empty (the default), the command tools are not registered at all - the feature is completely off.

Suggested commands by stack

| Category | Commands | |---|---| | Git | git pull, git status, git log --oneline -10, git diff | | npm | npm install, npm test, npm run build, npm run lint | | PM2 | pm2 status, pm2 restart all, pm2 reload all, pm2 logs --lines 50 | | Laravel | php artisan migrate, php artisan cache:clear, composer install | | Python | pip install -r requirements.txt, python manage.py migrate | | Docker | docker ps, docker-compose up -d, docker-compose down | | System | df -h, free -m |

Security

• Commands run with no shell (shell: false) - shell metacharacters like ;, &&, | are inert
• Exact match only - npm test; rm -rf / won't match npm test
• Output is capped at 10 KB to prevent context flooding
• Default timeout: 30 seconds (configurable via COMMAND_TIMEOUT_MS)
• Commands run in BASE_PATH as their working directory

Configuration Reference

| Variable | Required | Default | Description | |---|---|---|---| | PORT | No | 3000 | Port the server listens on | | BASE_PATH | Yes | - | Default directory Claude can access | | BEARER_TOKEN | Yes | - | Secret auth token | | WORKSPACES | No | (none) | Extra named directories (name:/path,...) | | ALLOWED_COMMANDS | No | (none) | Whitelisted shell commands (comma-separated) | | COMMAND_TIMEOUT_MS | No | 30000 | Max execution time per command (ms) |

Security

FileBridge MCP is built with security as a first principle:

| Threat | How FileBridge handles it | |---|---| | Unauthenticated access | Every request requires a valid Bearer token | | Token brute-force timing | Constant-time comparison (crypto.timingSafeEqual) | | Path traversal (../../etc/passwd) | All paths resolved and validated against workspace base | | Escaping the sandbox | Hard block - anything outside the allowed directory is rejected | | Shell injection in commands | spawn(shell:false) - metacharacters are never interpreted | | Arbitrary command execution | Exact-match whitelist - only pre-approved strings run | | Regex DoS | Invalid patterns caught and rejected before execution | | Binary file corruption | Non-UTF-8 files silently skipped in bulk operations |

Production security checklist

• [ ] HTTPS enabled (nginx + certbot)
• [ ] Strong random token (32+ bytes of entropy)
• [ ] BASE_PATH set to minimum required folder
• [ ] ALLOWED_COMMANDS limited to only what Claude needs
• [ ] Server running as non-root user
• [ ] .env not committed to version control

To revoke access instantly:

# Change the token in .env, then:
pm2 restart filebridge-mcp

Authentication

FileBridge MCP accepts the token from two places so it works with every Claude client:

| Method | Format | Best for | |---|---|---| | URL query param | ?token=YOUR_TOKEN | claude.ai custom connector | | Authorization header | Authorization: Bearer YOUR_TOKEN | Claude Code, API, curl |

Project Structure

filebridge-mcp/
├── src/
│   ├── server.js              # Express + MCP SSE wiring
│   ├── config.js              # Config loader (.env / config.json)
│   ├── middleware/
│   │   └── auth.js            # Token auth (timing-safe, header + query param)
│   ├── tools/
│   │   ├── index.js           # Tool registration entry point
│   │   ├── fileTools.js       # read, write, list, delete
│   │   ├── projectTools.js    # search, replace, structure
│   │   ├── commandTools.js    # run_command, list_allowed_commands
│   │   └── workspaceTools.js  # list_workspaces
│   └── utils/
│       ├── pathGuard.js       # Path traversal prevention + workspace prefix
│       └── logger.js          # Timestamped console logger
├── config.json                # Optional file-based config (with suggestedCommands)
├── .env.example               # Environment variable template
├── claude-mcp-config.json     # Claude Code connection snippet
├── package.json
└── .gitignore

Troubleshooting

Access denied: path escapes the allowed base directory → Use relative paths only (e.g. src/index.js, not /var/www/src/index.js).

Unknown workspace: "name" → The workspace isn't configured. Call list_workspaces to see what's available, then check your .env or config.json.

Command not allowed: "..." → The command isn't in ALLOWED_COMMANDS. Check your .env - the string must be an exact match.

401 Unauthorized → Token is missing. Add ?token=YOUR_TOKEN to the URL (claude.ai) or the Authorization header (API/Claude Code).

403 Forbidden → Token is wrong. Double-check your .env value and what you pasted into the connector form.

Session not found → The SSE session expired. Claude reconnects automatically.

Connection fails in claude.ai but works with curl → Your server isn't reachable from Anthropic's cloud. Check that nginx is running, port 443 is open in your firewall, and your TLS certificate is valid (sudo certbot renew --dry-run).

Contributing

Contributions are welcome! Feel free to open issues or pull requests for:

• New tools (e.g. move_file, create_directory)
• OAuth 2.0 support for multi-user deployments
• Docker / docker-compose setup
• One-click deploy buttons (Railway, Render, Fly.io)

License

MIT - free to use, modify, and distribute.

FileBridge MCP - the simplest way to connect Claude.ai to your project files.

Powered by WebifyGO