An MCP proxy server that aggregates and serves multiple MCP resource servers through a single HTTP server.
- Proxy Multiple MCP Clients: Connects to multiple MCP resource servers and aggregates their tools and capabilities.
- SSE Support: Provides an SSE (Server-Sent Events) server for real-time updates.
- Flexible Configuration: Supports multiple client types (
stdio,sseorstreamable-http) with customizable settings.
git clone https://github.com/TBXark/mcp-proxy.git
cd mcp-proxy
make build
# Create your own configuration file (see Security Configuration below)
cp config.json.example config.json
# Edit config.json and fill in your tokens
./build/mcp-proxy --config path/to/config.jsongo install github.com/TBXark/mcp-proxy@latestThe Docker image supports two MCP calling methods by default:
npxanduvx.
# Create and configure your config.json first
docker run -d -p 9090:9090 -v /path/to/config.json:/config/config.json ghcr.io/tbxark/mcp-proxy:latest
# or
docker run -d -p 9090:9090 ghcr.io/tbxark/mcp-proxy:latest --config https://example.com/path/to/config.jsonThe server is configured using a JSON file. Below is an example configuration:
This is the format for the new version's configuration. The old version's configuration will be automatically converted to the new format's configuration when it is loaded.
You can use
https://tbxark.github.io/mcp-proxyto convert the configuration ofmcp-proxyinto the configuration thatClaudecan use.
- The project provides
config.json.exampleas a template. Do NOT commit your actual configuration file to version control systems - When creating your own configuration, copy the example file and rename it to
config.json - In your
config.json, replace all placeholders (likeYOUR_DEFAULT_TOKEN_HERE) with actual values - Ensure
.gitignorealready includesconfig.json(included by default) - For production environments, consider using environment variables or secure key management systems
Common options for mcpProxy and mcpServers.
panicIfInvalid: If true, the server will panic if the client is invalid.logEnabled: If true, the server will log the client's requests.authTokens: A list of authentication tokens for the client. TheAuthorizationheader will be checked against this list.toolFilter: Optional tool filtering configuration. This configuration is only effective inmcpServers.mode: Specifies the filtering mode. Must be explicitly set toalloworblockiflistis provided. Iflistis present butmodeis missing or invalid, the filter will be ignored for this server.list: A list of tool names to filter (either allow or block based on themode).
Tip: If you don't know the exact tool names, run the proxy once without any
toolFilterconfigured. The console will log messages like<server_name> Adding tool <tool_name>for each successfully registered tool. You can use these logged names in yourtoolFilterlist.
In the new configuration, the
authTokensofmcpProxyis not a global authentication token, but rather the default authentication token formcpProxy. WhenauthTokensis set inmcpServers, the value ofauthTokensinmcpServerswill be used instead of the value inmcpProxy. In other words, theauthTokensofmcpProxyserves as a default value and is only applied whenauthTokensis not set inmcpServers.
Other fields are the same.
Proxy HTTP server configuration
baseURL: The public accessible URL of the server. This is used to generate the URLs for the clients.addr: The address the server listens on.name: The name of the server.version: The version of the server.options: Default options for themcpServers.
MCP server configuration, Adopt the same configuration format as other MCP Clients.
transportType: The transport type of the MCP client. Except forstreamable-http, which requires manual configuration, the rest will be automatically configured according to the content of the configuration file.stdio: The MCP client is a command line tool that is run in a subprocess.sse: The MCP client is a server that supports SSE (Server-Sent Events).streamable-http: The MCP client is a server that supports HTTP streaming.
For stdio mcp servers, the command field is required.
command: The command to run the MCP client.args: The arguments to pass to the command.env: The environment variables to set for the command.options: Options specific to the client.
For sse mcp servers, the url field is required. When the current url exists, sse will be automatically configured.
url: The URL of the MCP client.headers: The headers to send with the request to the MCP client.
For http streaming mcp servers, the url field is required. and transportType need to manually set to streamable-http.
url: The URL of the MCP client.headers: The headers to send with the request to the MCP client.timeout: The timeout for the request to the MCP client.
Usage of mcp-proxy:
-config string
path to config file or a http(s) url (default "config.json")
-help
print help and exit
-version
print version and exit
- The server will start and aggregate the tools and capabilities of the configured MCP clients.
- You can access the server at
http(s)://{baseURL}/{clientName}/sse. (e.g.,https://mcp.example.com/fetch/sse, based on the example configuration) - If your MCP client does not support custom request headers., you can change the key in
clientssuch asfetchtofetch/{authToken}, and then access it viafetch/{authToken}.
- This project was inspired by the adamwattis/mcp-proxy-server project
- If you have any questions about deployment, you can refer to 《在 Docker 沙箱中运行 MCP Server》(@ccbikai)
This project is licensed under the MIT License. See the LICENSE file for details.
{ "mcpProxy": { "baseURL": "https://mcp.example.com", "addr": ":9090", "name": "MCP Proxy", "version": "1.0.0", "options": { "panicIfInvalid": false, "logEnabled": true, "authTokens": [ "YOUR_DEFAULT_TOKEN_HERE" // Replace with your actual token ] } }, "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-github" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN_HERE" // Replace with your actual GitHub token }, "options": { "toolFilter": { "mode": "block", "list": [ "create_or_update_file" ] } } }, "fetch": { "command": "uvx", "args": [ "mcp-server-fetch" ], "options": { "panicIfInvalid": true, "logEnabled": false, "authTokens": [ "YOUR_SPECIFIC_TOKEN_HERE" // Replace with your actual token ] } }, "amap": { "url": "https://mcp.amap.com/sse?key=YOUR_AMAP_KEY_HERE" // Replace with your actual API key } } }