# Claude MCP server gateway

A Python MCP server gateway for Claude Desktop, Claude Code, Cline and Roo. Instead of loading all MCP tools at startup, it loads them on demand.

**Works with:** Claude Desktop (app), Claude Code (terminal), Cline  and Roo (VSCode extensions)

## Compatibility

| Platform | Config File | Supported |
|----------|------------|----------|
| Claude Desktop | `claude_desktop_config.json` | Yes |
| Claude Code | `.claude.json` or `.mcp.json` | Yes |
| Cline (VSCode) | `cline_mcp_settings.json` | Yes |

## The MCP server problem

When you connect multiple MCP servers to Claude:
- GitHub MCP server: 51 tools
- Slack MCP server: 20 tools  
- Google Drive MCP: 15 tools
- Filesystem MCP: 12 tools

That's 100+ MCP tool definitions loaded before you even start. Each tool's JSON schema eats up tokens.

## What this Claude MCP server gateway does

The gateway acts as a single MCP server with 3 tools:
1. `list_available_mcps` - shows configured MCP servers
2. `load_mcp_tools` - loads tools from a specific MCP server
3. `call_mcp_tool` - executes the tool

Model Context Protocol servers only start when Claude actually needs them.

## Setup

### Requirements
- Python 3.11+ (for MCP Python SDK)
- Claude Desktop, Claude Code, or Cline/Roo
- MCP servers you want to use

### Install

```bash
git clone https://github.com/bzsasson/claude-mcp-server-gateway.git
cd claude-mcp-server-gateway

python3.11 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install mcp python-dotenv
```

### Configure API keys

```bash
cp .env.example .env
# Edit .env with your tokens
```

## Claude Desktop MCP server configuration

Add to your Claude Desktop config:

**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`  
**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gateway": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/claude-mcp-server-gateway/dcl_wrapper.py"]
    }
  }
}
```

Restart Claude Desktop.

## How to add MCP server to Claude Code

Claude Code MCP server setup uses a similar config with one additional field.

### User-level configuration (all projects)

Edit `~/.claude.json`:

```json
{
  "mcpServers": {
    "gateway": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/claude-mcp-server-gateway/dcl_wrapper.py"]
    }
  }
}
```

### Project-level configuration

For project-specific MCP servers, create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "gateway": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/claude-mcp-server-gateway/dcl_wrapper.py"]
    }
  }
}
```

Claude Code will prompt for approval when using project-scoped servers.

### Alternative: Claude Code CLI

```bash
# Add the gateway using CLI
claude mcp add gateway --scope user \
  --command /path/to/.venv/bin/python \
  -- /path/to/claude-mcp-server-gateway/dcl_wrapper.py

# Verify it's added
claude mcp list
```

## Cline/Roo MCP server configuration

For Cline and Roo (VSCode extensions), the MCP server gateway configuration goes in:

**Mac**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`  
**Windows**: `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`  
**Linux**: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

```json
{
  "mcpServers": {
    "gateway": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/claude-mcp-server-gateway/dcl_wrapper.py"],
      "disabled": false
    }
  }
}
```

Restart VSCode after updating.

## How it works

1. Claude starts - sees gateway (3 tools)
2. You ask about GitHub - Claude calls `list_available_mcps`
3. Claude sees GitHub available - calls `load_mcp_tools("github")`  
4. Gateway returns GitHub's tool list
5. Claude picks the right tool - calls `call_mcp_tool("github", "search_repositories", {...})`
6. Gateway spins up GitHub MCP, runs the tool, returns results

## Adding MCP servers to the gateway

Edit `dcl_wrapper.py` and add to the `MCP_SERVERS` dict:

```python
MCP_SERVERS = {
    "your-server": {
        "command": "npx",
        "args": ["-y", "your-mcp-package"],
        "env": {
            "API_KEY": os.getenv("YOUR_API_KEY", "")
        },
        "description": "What it does"
    }
}
```

## Currently configured servers

- github
- slack  
- google-drive
- filesystem
- postgres
- memory
- brave-search

(Check `dcl_wrapper.py` for the full list)

## Limitations

- Small delay on first tool use (server startup)
- Each MCP server connection is temporary
- No persistence between calls

## Troubleshooting

### Gateway not appearing
- Check Python path in config points to virtual environment
- Verify `dcl_wrapper.py` path is correct
- Restart Claude Desktop/Code/VSCode completely

### MCP server connection errors
- Check API keys in `.env` file
- Verify MCP server package is installed
- Check gateway logs for errors

### Claude Code specific issues
- Make sure to include `"type": "stdio"` in config
- For project configs, approve when prompted
- Use `claude mcp list` to verify installation

## Files

- `dcl_wrapper.py` - The gateway server
- `.env` - Your API keys
- `requirements.txt` - Python dependencies

## License

MIT