MCP Proxy Server

简体中文

✨ Key Features Highlight

🌐 Web UI Management: Easily manage all connected MCP servers through an intuitive web interface (optional, requires enabling).
🔧 Granular Tool Control: Enable or disable individual tools, and override display names/descriptions via the Web UI.
🔒 Dual SSE Authentication: Secure your SSE endpoint with flexible authentication options (Authorization: Bearer <token> or X-API-Key: <key>).
🔄 Improved SSE Session Handling: More robust handling of client reconnections, relying on server-sent endpoint events for session synchronization.
✨ Real-time Install Output: Monitor Stdio server installation progress (stdout/stderr) directly in the Web UI.
✨ Web Terminal: Access a command-line terminal within the Admin UI for direct server interaction (optional, use with caution due to security risks).

This server acts as a central hub for Model Context Protocol (MCP) resource servers. It can:

Connect to and manage multiple backend MCP servers (both Stdio and SSE types).
Expose their combined capabilities (tools, resources) through a single, unified SSE interface or act as a single Stdio-based MCP server itself.
Handle routing of requests to the appropriate backend servers.
Aggregate responses if needed (though primarily acts as a proxy).
Support multiple simultaneous SSE client connections with optional API key authentication.

Features

Resource & Tool Management via Proxy

Discovers and connects to multiple MCP resource servers defined in config/mcp_server.json.
Aggregates tools and resources from all connected active servers.
Routes tool calls and resource access requests to the correct backend server.
Maintains consistent URI schemes.

✨ Optional Web Admin UI (`ENABLE_ADMIN_UI=true`)

Provides a browser-based interface for managing the proxy server configuration and connected tools. Features include:

Server Configuration: View, add, edit, and delete server entries (mcp_server.json). Supports both Stdio and SSE server types with relevant options (command, args, env, url, apiKey, bearerToken, install config).
Tool Configuration: View all tools discovered from active backend servers. Enable or disable specific tools. Override the display name and description for each tool (tool_config.json).
Live Reload: Apply server and tool configuration changes by triggering a configuration reload without needing to restart the entire proxy server process.
Stdio Server Installation: For Stdio servers, you can define installation commands in the configuration. The Admin UI allows you to:
- Trigger the execution of these installation commands.
- Monitor installation progress in real-time with live stdout and stderr output streamed directly to the UI.
Web Terminal: Access an integrated web-based terminal that provides shell access to the environment where the proxy server is running.
- Security Warning: This feature grants significant access and should be used with extreme caution, especially if the admin interface is exposed.

Configuration

Configuration is primarily done via environment variables and JSON files located in the ./config directory.

1. Server Connections (`config/mcp_server.json`)

This file defines the backend MCP servers the proxy should connect to.

Example config/mcp_server.json:

{
  "mcpServers": {
    "unique-server-key1": {
      "name": "My Stdio Server",
      "active": true,
      "command": "/path/to/server/executable",
      "args": ["--port", "1234"],
      "env": {
        "API_KEY": "server_specific_key"
      },
      "installDirectory": "/custom_install_path/unique-server-key1",
      "installCommands": [
        "git clone https://github.com/some/repo unique-server-key1",
        "cd unique-server-key1 && npm install && npm run build"
      ]
    },
    "another-sse-server": {
      "name": "My SSE Server",
      "active": true,
      "url": "http://localhost:8080/sse",
      "apiKey": "sse_server_api_key"
    },
    "stdio-default-install": {
        "name": "Stdio Server with Default Install Path",
        "active": true,
        "command": "my_other_server",
        "installCommands": ["echo 'Installing to default location...'"]
    }
  }
}

Fields:

mcpServers: (Required) An object where each key is a unique identifier for a backend server.
name: (Optional) A user-friendly display name for the server (used in Admin UI).
active: (Optional, default: true) Set to false to prevent the proxy from connecting to this server.
command: (Required for Stdio type) The command to execute the server process.
args: (Optional for Stdio type) An array of string arguments to pass to the command.
env: (Optional for Stdio type) An object of environment variables (KEY: "value") to set for the server process. These are merged with the proxy server's environment.
url: (Required for SSE type) The full URL of the backend server's SSE endpoint.
apiKey: (Optional for SSE type) An API key to send in the X-Api-Key header when the proxy connects to this specific backend SSE server.
bearerToken: (Optional for SSE type) A token to send in the Authorization: Bearer <token> header when connecting to this specific backend SSE server. (If both apiKey and bearerToken are provided, bearerToken takes precedence).
installDirectory: (Optional for Stdio type) The absolute path where the server itself should be installed (e.g., /opt/my-server-files). Used by the Admin UI's installation feature.
- If provided in mcp_server.json, this exact path is used.
- If omitted, the effective directory depends on the TOOLS_FOLDER environment variable (see Environment Variables section).
  - If TOOLS_FOLDER is set and not empty, the server will be installed in a subdirectory named after the server key within this folder (e.g., ${TOOLS_FOLDER}/<server_key>).
  - If TOOLS_FOLDER is also empty or not set, it defaults to a tools subdirectory within the proxy server's working directory (e.g., ./tools/<server_key>).
- Ensure the parent directory of the target installation path (e.g., TOOLS_FOLDER or ./tools) is writable by the user running the proxy server.
installCommands: (Optional for Stdio type) An array of shell commands executed sequentially by the Admin UI's installation feature if the target server directory (derived from installDirectory or defaults) does not exist. Commands are executed from the parent directory of the target server installation directory (e.g., if installDirectory resolves to /opt/tools/my-server, commands run in /opt/tools/). Use with extreme caution due to security risks.

2. Tool Configuration (`config/tool_config.json`)

This file allows overriding properties of tools discovered from backend servers. It is primarily managed via the Admin UI but can be edited manually.

Example config/tool_config.json:

{
  "tools": {
    "unique-server-key1--tool-name-from-server": {
      "enabled": true,
      "displayName": "My Custom Tool Name",
      "description": "A more user-friendly description."
    },
    "another-sse-server--another-tool": {
      "enabled": false
    }
  }
}

Keys are in the format <server_key>--<original_tool_name>.
enabled: (Optional, default: true) Set to false to hide this tool from clients connecting to the proxy.
displayName: (Optional) Override the tool's name in client UIs.
description: (Optional) Override the tool's description.

3. Environment Variables

PORT: Port for the proxy server's main SSE endpoint (and Admin UI if enabled). Default: 3663. Note: This is only used when running in SSE mode (e.g., via npm run dev:sse or the Docker container). The npm run dev script runs in Stdio mode.
```
export PORT=8080
```
MCP_PROXY_SSE_ALLOWED_KEYS: (Optional) Comma-separated list of API keys to secure the proxy's main /sse endpoint (only applicable in SSE mode). If not set, authentication is disabled. Clients must provide a key via X-Api-Key header or ?key= query parameter.
```
export MCP_PROXY_SSE_ALLOWED_KEYS="client_key1,client_key2"
```
ENABLE_ADMIN_UI: (Optional) Set to true to enable the Web Admin UI (only applicable in SSE mode). Default: false.
```
export ENABLE_ADMIN_UI=true
```
ADMIN_USERNAME: (Required if Admin UI enabled) Username for Admin UI login. Default: admin.
ADMIN_PASSWORD: (Required if Admin UI enabled) Password for Admin UI login. Default: password (Change this!).
```
export ADMIN_USERNAME=myadmin
export ADMIN_PASSWORD=aVerySecurePassword123!
```
SESSION_SECRET: (Optional, recommended if Admin UI enabled) Secret used to sign session cookies. If not set, a default, less secure secret is used, and a warning is issued. A secure secret is automatically generated and saved to config/.session_secret on first run if not provided via environment variable.
```
# Recommended: Generate a strong secret (e.g., openssl rand -hex 32)
export SESSION_SECRET='your_very_strong_random_secret_here'
```
TOOLS_FOLDER: (Optional) Specifies the base directory for Stdio server installations initiated via the Admin UI, used when installDirectory is not explicitly set in mcp_server.json for a specific server.
- If set (e.g., /custom/tools_path), installations for servers without a specific installDirectory will target a subdirectory named after the server key within this folder (e.g., ${TOOLS_FOLDER}/<server_key>).
- If TOOLS_FOLDER is not set or is empty, such installations will default to a tools subdirectory within the proxy server's working directory (e.g., ./tools/<server_key>).
- The Dockerfile sets this to /tools by default.
```
export TOOLS_FOLDER=/srv/mcp_tools
```

Development

Install dependencies:

npm install
# or yarn install

Build the server (compiles TypeScript to JavaScript in build/):

npm run build

Run in development mode (uses tsx for direct TS execution with auto-restart on changes):

# Run as a Stdio MCP server (default mode)
npm run dev

# Run as an SSE MCP server (enables SSE endpoint and Admin UI if configured)
# Ensure environment variables (PORT, ENABLE_ADMIN_UI etc.) are set as needed
ENABLE_ADMIN_UI=true npm run dev:sse

Watch for changes and rebuild automatically (useful if not using tsx):

npm run watch

Running with Docker

A Dockerfile is provided. The container runs the server in SSE mode by default (using build/sse.js) and includes all necessary dependencies. The TOOLS_FOLDER environment variable defaults to /tools inside the container.

Recommended: Using the Pre-built Image (from GHCR)

It's recommended to use the pre-built image from GitHub Container Registry for easier setup. We provide two types of images:

Standard Image (Lean): This is the default and recommended image for most users. It contains the core MCP Proxy Server functionality.

Tags: latest, <version> (e.g., 0.1.2)

# Pull the latest standard image
docker pull ghcr.io/${{ github.repository }}/mcp-proxy-server:latest

# Or pull a specific version
# docker pull ghcr.io/${{ github.repository }}/mcp-proxy-server:0.1.2

Bundled Image (Full-featured): This image includes a set of pre-installed MCP servers and Playwright browser dependencies. It's significantly larger but provides out-of-the-box access to common tools.
- Tag: <version>-bundled-mcpservers-playwright (e.g., 0.1.2-bundled-mcpservers-playwright) or latest-bundled-mcpservers-playwright
```
# Pull a bundled version
# docker pull ghcr.io/${{ github.repository }}/mcp-proxy-server:latest-bundled-mcpservers-playwright
```
The bundled image includes the following pre-installed components (via Docker build arguments):
- PIP Packages (PRE_INSTALLED_PIP_PACKAGES_ARG):
  - mcp-server-time
  - markitdown-mcp
  - mcp-proxy
- NPM Packages (PRE_INSTALLED_NPM_PACKAGES_ARG):
  - g-search-mcp
  - fetcher-mcp
  - playwright
  - time-mcp
  - mcp-trends-hub
  - @adenot/mcp-google-search
  - edgeone-pages-mcp
  - @modelcontextprotocol/server-filesystem
  - mcp-server-weibo
  - @variflight-ai/variflight-mcp
  - @baidumap/mcp-server-baidu-map
  - @modelcontextprotocol/inspector
- Initialization Command (PRE_INSTALLED_INIT_COMMAND_ARG):
  - playwright install --with-deps chromium

Choose the image type that best suits your needs. For most users, the standard image is sufficient, and backend MCP servers can be configured via mcp_server.json.

Then, run your chosen container image:

docker run -d \
  -p 3663:3663 \
  -e PORT=3663 \
  -e ENABLE_ADMIN_UI=true \
  -e ADMIN_USERNAME=myadmin \
  -e ADMIN_PASSWORD=yoursupersecretpassword \
  -e MCP_PROXY_SSE_ALLOWED_KEYS="clientkey1" \
  -e TOOLS_FOLDER=/my/custom_tools_volume # Optional: Override default /tools for server installations
  -v ./my_config:/app/config \
  -v /path/on/host/to/tools:/my/custom_tools_volume `# Mount a volume for TOOLS_FOLDER if overridden` \
  --name mcp-proxy \
  ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest

Replace ./my_config with your host path containing mcp_server.json and optionally tool_config.json. The container expects config files in /app/config.
If you override TOOLS_FOLDER for server installations via Admin UI, ensure you mount a corresponding volume (e.g., -v /path/on/host/for_tools:/my/custom_tools_volume). If using the default /tools (set by TOOLS_FOLDER in Dockerfile), you can mount to /tools (e.g., -v /path/on/host/to/tools_default:/tools).
Adjust the tag (:latest) if you pulled a specific version.
Set other environment variables using the -e flag as needed.

Building the Image Locally (Optional):

docker build -t mcp-proxy-server .

(If you build locally, use mcp-proxy-server instead of the ghcr.io/... image name in the docker run command above).

Installation & Usage with Clients

This proxy server can be used in two main ways:

1. As a Stdio MCP Server: Configure your MCP client (like Claude Desktop) to run the proxy server directly using its command (build/index.js). The proxy will then connect to the backend servers defined in its config/mcp_server.json.

Example for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-proxy": {
      "name": "MCP Proxy (Aggregator)",
      "command": "/path/to/mcp-proxy-server/build/index.js",
      "env": {
         "NODE_ENV": "production", // Optional: Set environment for the proxy itself
         "TOOLS_FOLDER": "/custom/path/for/proxy/tools" // Optional: If proxy needs to install its own backends
      }
    }
  }
}

Replace /path/to/mcp-proxy-server/build/index.js with the actual path to the built entry point of this proxy server project. Ensure the config directory is correctly located relative to where the command is run, or use absolute paths in the proxy's own config if needed.

2. As an SSE MCP Server: Run the proxy server in SSE mode (e.g., npm run dev:sse or the Docker container). Then, configure your MCP client to connect to the proxy's SSE endpoint. If API key authentication is enabled on the proxy (MCP_PROXY_SSE_ALLOWED_KEYS), provide the key in the client configuration, preferably via the URL query parameter ?key=... for broader client compatibility.

Example for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "my-proxy-sse": {
      "name": "MCP Proxy (SSE)",
      // Append ?key=<your_key> if authentication is enabled
      "url": "http://localhost:3663/sse?key=clientkey1"
      // The apiKey field might not be supported by all clients for SSE auth
      // "apiKey": "clientkey1"
    }
  }
}

Debugging

Use the MCP Inspector for debugging communication (primarily for Stdio mode):

npm run inspector

This script wraps the execution of the built server (build/index.js) with the inspector. Access the inspector UI via the URL provided in the console output. For SSE mode, standard browser developer tools can be used to inspect network requests.

Reference

This project was originally inspired by and refactored from adamwattis/mcp-proxy-server.

MCP Proxy Server

MCP Proxy Server

✨ Key Features Highlight

Features

Resource & Tool Management via Proxy

✨ Optional Web Admin UI (ENABLE_ADMIN_UI=true)

Configuration

1. Server Connections (config/mcp_server.json)

2. Tool Configuration (config/tool_config.json)

3. Environment Variables

Development

Running with Docker

Installation & Usage with Clients

Debugging

Reference

✨ Optional Web Admin UI (`ENABLE_ADMIN_UI=true`)

1. Server Connections (`config/mcp_server.json`)

2. Tool Configuration (`config/tool_config.json`)