MCP Stdio Bridge

A generic, professional-grade gateway that bridges Model Context Protocol (MCP) servers between SSE (Server-Sent Events) and Stdio transports.

Features

• Generic Bridge: Works with any executable that speaks MCP over stdio.

• Command Wrapper Mode: Directly wrap any CLI utility (like wp-cli, git, or custom scripts) into a restricted MCP server without writing external scripts.

• Dual Transport Support: Run over SSE (HTTP/HTTPS) for remote access or Stdio for local use by MCP clients.

• 100% Test Coverage: Exhaustive test suite ensuring stability across all transports, operational modes, and failure paths.

• YAML Configuration: Easily manage settings via a central config file.

• Dynamic Configuration Reload: Opt-in feature to live-reload settings from config.yaml without dropping active sessions — via the --watch-config file watcher or by sending SIGHUP on POSIX systems.

• Daemon Mode: --daemonize performs a POSIX double-fork to detach from the terminal; pair with --pid-file for init system and supervisor integration.

• Idle Session Timeouts: Automatically terminates stalled proxy and wrapper sessions to prevent resource leaks.

• Process Management: Automatically spawns, manages, and cleans up subprocesses for bridging.

• Security:

  • API key authentication (Header or Query Param).
  • Restricted argument prefixing and regex filtering for wrapped commands.
  • Built-in Directory Traversal Protection for local tool execution.
  • Environment Scrubbing: Allowlist/Denylist variables passed to subprocesses.
  • Secret Masking: Sensitive keys are automatically hidden from logs.
  • Connection limiting and message size throttling.
  • SSL/TLS with client certificate and CRL support.
  • HSTS and secure security headers.

Installation

Install the package using pip:

pip install mcp-stdio-bridge

Documentation

For detailed information on configuring and deploying the bridge, see:

• docs/configuration.md: Full settings reference and JSON Schema.
• docs/deployment.md: Docker and local execution guides.
• docs/mcp-servers.md: Integration requirements for MCP servers.
• docs/roadmap.md: Future considerations and planned features.

Architecture & Design

To understand the internal logic and security model, refer to:

• docs/architecture.md: Modular structure and transport/mode design.
• docs/security.md: Detailed security features and sandboxing.
• docs/workflows.md: Sequential operational flows.

Examples

Check the examples/ directory for templates covering common use cases:

• wp-cli-wrapper.yaml: Manage WordPress via MCP (Mix of Allowlist/Denylist).
• git-wrapper.yaml: Expose Git operations to local clients (Allowlist-only).
• sqlite-proxy.yaml: Bridge an existing SQLite MCP server to SSE.
• security-patterns.yaml: Advanced regex-based security filtering.
• docker-tool-wrapper.yaml: Using custom environment variables per tool.

Example config.yaml:

host: "127.0.0.1"
port: 8000
command: "python your_mcp_server.py"
verbose: true
api_key: "your-secret-key"
max_connections: 5
cors_origins: ["*"]
# ssl_keyfile: "path/to/key.pem"
# ssl_certfile: "path/to/cert.pem"

Running the Bridge

mcp-stdio-bridge

Docker

You can run the bridge using Docker:

# Build the image
docker build -t mcp-stdio-bridge .

# Run with a mounted config file
docker run -p 8000:8000 -v $(pwd)/config.yaml:/app/config.yaml mcp-stdio-bridge

Alternatively, use Docker Compose:

docker-compose up -d

Customization Arguments

Note: When operating in Stdio transport mode, all non-JSON-RPC output (including warnings, errors, and informational logs) is directed to sys.stderr to maintain JSON-RPC stream integrity.

Development

Install all dependencies (including test and dev extras):

pip install -e ".[dev,test]"

Run the full test suite (the --timeout=10 flag is required — SSE transport tests can hang without it):

pytest --timeout=10

Lint, type-check, and security scan:

ruff check src tests
mypy src
bandit -r src -c pyproject.toml

Standalone Integration Tests

End-to-end integration tests live in standalone_tests/. They exercise real transport and subprocess paths outside the unit-test harness, including SSH and Docker scenarios. See docs/deployment.md for full usage instructions.

# Quick local smoke test (no Docker required)
./standalone_tests/run_tests.sh

License

This is free and unencumbered software released into the public domain. For more information, please refer to the LICENSE file or http://unlicense.org/.