MCP Hub

Internal MCP (Model Context Protocol) server and AI tools platform for the homelab. Acts as a single gateway that aggregates dozens of upstream MCP servers — your AIs connect once and get access to everything.

How It Works

Claude Code / Claude Desktop / Any MCP Client
            │
            ▼
    ┌───────────────┐
    │   MCP Hub     │  ← single SSE connection
    │  (FastAPI)    │
    └──────┬────────┘
           │
    ┌──────┴────────────────────────────────┐
    │                                       │
    ▼              ▼              ▼         ▼
 Local Tools    GitHub MCP    Brave MCP   Wikipedia MCP
 (GitLab,K8s,   (stdio)       (stdio)     (stdio)
  Homelab)        ...           ...         ...

Your AI connects to one endpoint and gets access to:

• 15 built-in local tools (GitLab, Kubernetes, Homelab)
• 30+ upstream MCP servers (search, databases, code, AI, monitoring, communication)

Quick Start

cd ~/projects/homelab/mcp-hub
export MH_GITLAB_TOKEN=<your-gitlab-pat>
export MH_GITHUB_TOKEN=<your-github-token>
docker compose up -d

# Dashboard: http://localhost:8500
# MCP SSE:   http://localhost:8500/mcp/sse

Connect Your AI

Add to Claude Code settings.json:

{
  "mcpServers": {
    "mcp-hub": {
      "type": "sse",
      "url": "http://mcp-hub.steelcanvas.dev/mcp/sse"
    }
  }
}

That's it. One connection, all tools.

Available Upstream Servers

Configured in upstreams.yaml. Enabled by default (no API key needed):

Set an API key to enable:

Adding Custom Upstream Servers

Edit upstreams.yaml:

upstreams:
  # stdio-based (spawns a local process)
  my-server:
    transport: stdio
    enabled: true
    description: "My custom MCP server"
    command: npx
    args: ["-y", "my-mcp-package"]
    env:
      API_KEY: "${MH_MY_API_KEY}"
    prefix: my

  # SSE-based (connects to a remote HTTP endpoint)
  remote-server:
    transport: sse
    enabled: true
    description: "Remote MCP server"
    url: "http://192.168.1.50:9000/mcp/sse"
    headers:
      Authorization: "Bearer ${MH_REMOTE_TOKEN}"
    prefix: remote

API Endpoints

Architecture

mcp-hub/
├── mcp_hub/
│   ├── main.py            # FastAPI app + dashboard + proxy lifecycle
│   ├── mcp_server.py      # MCP server (FastMCP) with local tools
│   ├── config.py          # Pydantic settings (MH_* env vars)
│   ├── database.py        # SQLAlchemy async engine
│   ├── models/            # ORM models (ToolLog)
│   ├── tools/             # Built-in local tools
│   │   ├── gitlab_tools.py
│   │   ├── k8s_tools.py
│   │   └── homelab_tools.py
│   └── proxy/             # Upstream MCP proxy engine
│       ├── manager.py     # Orchestrates connections, registers proxied tools
│       ├── connector.py   # MCP client for a single upstream (stdio/SSE)
│       ├── registry.py    # Server config dataclass + YAML loader
│       ├── defaults.py    # Built-in default upstream configs
│       └── env_resolver.py # ${VAR} placeholder resolution
├── upstreams.yaml         # User-editable upstream config
├── templates/             # Jinja2 dashboard
├── static/css/            # Dark-themed dashboard styles
├── Dockerfile             # Multi-stage (Python + Node.js for npx)
├── docker-compose.yml     # Local dev stack
└── .gitlab-ci.yml         # CI/CD pipeline

Development

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

# Run locally
export MH_DATABASE_URL=postgresql+asyncpg://mcphub:mcphub@localhost:5432/mcphub
uvicorn mcp_hub.main:app --reload --port 8500

# Lint & test
ruff check .
pytest -v