Labsco
delexw logo

Gateway MCP Server

★ 4

from delexw

A gateway server that intelligently routes MCP requests to multiple backend servers.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#database#devops#git

Gateway MCP Server

mcpware Logo

Route MCP requests intelligently to multiple backend servers.

🎯 Key Features

🚀 Bypass Tool Limits

  • Challenge: MCP clients often have limits on how many tools can be loaded at once
  • Solution: mcpware exposes only 2 routing tools while providing access to unlimited backend tools
  • Result: Connect to GitHub (50+ tools), databases, and more through a single gateway!

🔧 Additional Benefits

  • Single entry point for multiple MCP servers
  • Automatic process management for backend servers
  • Docker-based isolation and deployment

How it Works

mcpware runs as a Docker container that:

  1. Receives requests from MCP clients via stdio
  2. Routes them to the appropriate backend MCP server (also running in Docker)
  3. Returns responses back to MCP client

Important: Backend servers can use any command (docker, npx, node, python, etc.). When running mcpware in Docker, backends using local commands like npx or node will execute inside the mcpware container.

Using mcpware Alongside Other MCP Servers

mcpware is designed to work alongside other MCP servers in your MCP client configuration. You can:

  1. Use mcpware as a gateway for multiple backend servers
  2. Keep some MCP servers separate for direct access
  3. Mix and match based on your needs

Example mixed configuration:

{
  "mcpServers": {
    "mcpware": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/mcpware/config.json:/app/config.json:ro",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "--env-file", "/path/to/mcpware/.env",
        "mcpware"
      ]
    },
    "redis-direct": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "REDIS_HOST=localhost", "mcp/redis"]
    }
  }
}

This allows you to:

  • Access multiple servers through mcpware when you need routing
  • Connect directly to specific servers when you need dedicated access
  • Organize your MCP servers based on your workflow

Development

Prerequisites

Ensure you have Python 3.10+ installed:

python --version  # Should show Python 3.10 or higher

Development Setup

  1. Clone the repository:

    git clone https://github.com/delexw/mcpware.git
cd mcpware

  2. Create a virtual environment (recommended):

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install development dependencies:

    pip install -r requirements.txt

Development Dependencies

The project uses minimal dependencies. All core functionality is implemented using the Python standard library.

Testing dependencies (included in requirements.txt):

  • pytest - Testing framework
  • pytest-asyncio - Async test support
  • pytest-cov - Code coverage reporting

Optional development tools (install separately if needed):

# Code formatting
pip install black isort

# Linting
pip install flake8 pylint mypy

# Development convenience
pip install pytest-watch  # Auto-run tests on file changes

Running Locally

# Run the gateway server
python gateway_server.py --config config.json

# Run with debug logging
python gateway_server.py --config config.json --log-level DEBUG

Code Style

Format your code before committing:

# Format with black (if installed)
black src/ tests/ gateway_server.py

# Sort imports (if installed)
isort src/ tests/ gateway_server.py

# Run linting (if installed)
flake8 src/ tests/ gateway_server.py --max-line-length=120

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=src --cov=gateway_server --cov-report=html

# Run specific test file
pytest tests/test_config.py

# Run tests in watch mode (requires pytest-watch)
pytest-watch

Docker

Build and run with Docker:

# Build the image
docker build -t mcpware .

# Run interactively (for testing)
docker run -it --rm \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  mcpware

# Run with specific config file
docker run -it --rm \
  -v /path/to/your/config.json:/app/config.json:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  mcpware

Environment Variables

The gateway supports environment variable substitution in backend configurations. Set these in your .env file:

# Example .env file
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
# Add other tokens as needed

Environment variables referenced in config.json using ${VAR_NAME} syntax will be automatically substituted.

Testing

The project includes comprehensive unit and integration tests.

Running Tests

  1. Install test dependencies:

    pip install -r requirements.txt

  2. Run all tests:

    pytest

  3. Run tests with coverage:

    pytest --cov=src --cov=gateway_server --cov-report=html

  4. Run specific test modules:

    pytest tests/test_config.py
pytest tests/test_backend.py
pytest tests/test_protocol.py

  5. Run tests in watch mode:

    pytest-watch