MCP Hub

Option A — Docker Compose

```bash git clone https://github.com/badhope/MCP-HUB.git cd MCP-HUB docker compose up -d --build

Quick start

Option B — Local Python

pip install -r requirements.txt
python tools/sync_index.py          # one-time, populates servers-index.json
python main.py                      # API on :8080

In a second terminal:

cd frontend
npm install
npm run dev                         # UI on :5173, proxies /servers to :8080

Option C — REST only

curl http://localhost:8080/health
curl "http://localhost:8080/servers?search=github&limit=5"
curl http://localhost:8080/config/github-mcp-server

GET /health is the only path the orchestrator needs to poll. Everything else is JSON.

---

Generate a config

cfg = httpx.get("https://mcp-hub.example.com/config/github-mcp-server").json() ```

A coding-agent-side conventions file is at AGENTS.md. For end-user agent integrations, see docs/internal/AGENT_GUIDE.md.

---

REST API: http://localhost:8080

API docs: http://localhost:8080/docs

```

The compose file wires the backend to a hot-reloadable dev frontend. First boot pulls the upstream index (~5 MB) and caches it in servers-index.json (gitignored, rebuild with python tools/sync_index.py).

REST API

main:app is a single FastAPI process. The OpenAPI schema is served at /openapi.json; interactive UIs at /docs (Swagger) and /redoc.

GET /servers supports: search, category, language, sort (stars / updated), min_stars, limit, offset.

Two pieces of cross-cutting behaviour worth knowing about — see docs/API.md for the full reference:

- GZip. Responses ≥ 1 KB are gzipped by FastAPI's built-in middleware. servers.json drops from ~100 KB to <15 KB on the wire. - Rate limit. Per-IP token bucket, default 120 req / 60 s. Exempts /, /health, /docs, /redoc, /openapi.json, and CORS preflight. Tunable via RATE_LIMIT_REQUESTS / RATE_LIMIT_WINDOW / RATE_LIMIT_TRUST_PROXY / RATE_LIMIT_DISABLED. For horizontal scale, terminate the limit at a reverse proxy.

---