mcp-proxy

2371 GitHub stars recorded

Installing via PyPI

The stable version of the package is available on the PyPI repository. You can install it using the following command:

# Option 1: With uv (recommended)
uv tool install mcp-proxy

# Option 2: With pipx (alternative)
pipx install mcp-proxy

Once installed, you can run the server using the mcp-proxy command. See configuration options for each mode above.

Installing via Github repository (latest)

The latest version of the package can be installed from the git repository using the following command:

uv tool install git+https://github.com/sparfenyuk/mcp-proxy

[!NOTE] If you have already installed the server, you can update it using uv tool upgrade --reinstall command.

[!NOTE] If you want to delete the server, use the uv tool uninstall mcp-proxy command.

Installing as container

Starting from version 0.3.2, it's possible to pull and run the corresponding container image. Release images are published to GHCR and Docker Hub as multi-platform manifests for linux/amd64 and linux/arm64; Docker selects the matching image for the host architecture automatically.

docker run --rm -t ghcr.io/sparfenyuk/mcp-proxy:v0.12.0 --help
docker run --rm -t sparfenyuk/mcp-proxy:v0.12.0 --help

Troubleshooting

• Problem: Claude Desktop can't start the server: ENOENT code in the logs

  Solution: Try to use the full path to the binary. To do so, open a terminal and run the commandwhich mcp-proxy ( macOS, Linux) or where.exe mcp-proxy (Windows). Then, use the output path as a value for 'command' attribute:

    "fetch": {
      "command": "/full/path/to/bin/mcp-proxy",
      "args": [
        "http://localhost:8932/sse"
      ]
    }
  

• NAME is used in the URL path /servers/NAME/.
• COMMAND_STRING is the command to start the server (e.g., 'uvx mcp-server-fetch').
  • Can be used multiple times.
  • This argument is ignored if --named-server-config is used.
• FILE_PATH - If provided, this is the exclusive source for named servers, and --named-server CLI arguments are ignored.

If a default server is specified (the command_or_url argument without --named-server or --named-server-config), it will be accessible at the root paths (e.g., http://127.0.0.1:8080/sse).

Named servers (whether defined by --named-server or --named-server-config) will be accessible under /servers/<server-name>/ (e.g., http://127.0.0.1:8080/servers/fetch1/sse). The /status endpoint provides global status.

JSON Configuration File Format for --named-server-config:

The JSON file should follow this structure:

{
  "mcpServers": {
    "fetch": {
      "disabled": false,
      "timeout": 60,
      "command": "uvx",
      "args": [
        "mcp-server-fetch"
      ],
      "transportType": "stdio"
    },
    "github": {
      "timeout": 60,
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      },
      "transportType": "stdio"
    }
  }
}

• mcpServers: A dictionary where each key is the server name (used in the URL path, e.g., /servers/fetch/) and the value is an object defining the server.
• command: (Required) The command to execute for the stdio server.
• args: (Optional) A list of arguments for the command. Defaults to an empty list.
• enabled: (Optional) If false, this server definition will be skipped. Defaults to true.
• timeout and transportType: These fields are present in standard MCP client configurations but are currently ignored by mcp-proxy when loading named servers. The transport type is implicitly "stdio".