<div align="center">

# 🔱 MCPHub

**One gateway to rule them all**

[![npm version](https://img.shields.io/npm/v/mcphub?color=blue)](https://www.npmjs.com/package/mcphub)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/NeuZhou/mcphub?style=social)](https://github.com/NeuZhou/mcphub)
[![CI](https://github.com/NeuZhou/mcphub/actions/workflows/ci.yml/badge.svg)](https://github.com/NeuZhou/mcphub/actions)

*A unified gateway and dashboard for managing multiple MCP (Model Context Protocol) servers.*
*Think "Docker Compose + Dashboard" for MCP servers.*

[Quick Start](#-quick-start) · [Features](#-features) · [Config Reference](#-config-reference) · [Contributing](#-contributing)

</div>

---

## 😩 Why MCPHub?

If you work with AI tools in 2026, you probably have **multiple MCP servers** — filesystem, GitHub, databases, APIs. Managing them is painful:

- ❌ **Scattered configs** — every AI client needs its own MCP server list
- ❌ **No visibility** — which servers are running? What tools are available?
- ❌ **No single endpoint** — each client connects to each server separately
- ❌ **Restart hell** — add a server = restart everything

MCPHub fixes all of this:

- ✅ **One YAML file** to define all your MCP servers
- ✅ **One gateway endpoint** that routes to the right server
- ✅ **Beautiful dashboard** showing status, tools, and stats
- ✅ **Hot reload** — edit config, servers update instantly

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────┐
│                   AI Clients                     │
│         (Claude, Cursor, Copilot, etc.)          │
└──────────────────┬──────────────────────────────┘
                   │  MCP Protocol (stdio)
                   ▼
┌─────────────────────────────────────────────────┐
│              🔱 MCPHub Gateway                   │
│                                                  │
│   ┌──────────┐ ┌──────────┐ ┌───────────────┐  │
│   │ Registry │ │ Router   │ │  Health Check  │  │
│   └──────────┘ └──────────┘ └───────────────┘  │
│                                                  │
│   ┌──────────────────────────────────────────┐  │
│   │        🌐 Web Dashboard (:3000)          │  │
│   └──────────────────────────────────────────┘  │
└──────┬──────────────┬──────────────┬────────────┘
       │              │              │
       ▼              ▼              ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ filesystem │ │   github   │ │  postgres  │
│   server   │ │   server   │ │   server   │
└────────────┘ └────────────┘ └────────────┘
```

## 🚀 Quick Start

**1. Install**
```bash
npm install -g mcphub
```

**2. Create `mcphub.yaml`**
```yaml
mcphub:
  port: 3000

servers:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]

  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
```

**3. Run**
```bash
mcphub
```

Open `http://localhost:3000` to see the dashboard 🎉

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🔱 **Unified Gateway** | Single MCP endpoint that routes to all downstream servers |
| 📋 **One Config** | Define all MCP servers in one `mcphub.yaml` file |
| 🌐 **Web Dashboard** | Beautiful dark-themed UI showing servers, tools, and stats |
| 🔄 **Hot Reload** | Edit config → servers update automatically, no restart needed |
| 🔍 **Tool Discovery** | Auto-discovers all tools from all connected servers |
| 💓 **Health Checks** | Periodic health monitoring of all downstream servers |
| 📊 **Usage Stats** | Request counts and error tracking per server |
| 🔌 **Env Variables** | Reference `${ENV_VARS}` in your config |

## 📖 Config Reference

```yaml
mcphub:
  port: 3000            # Dashboard port (default: 3000)
  log_level: info       # debug | info | warn | error

servers:
  - name: my-server     # Unique server name (required)
    command: npx         # Command to start the server (required)
    args: ["-y", "pkg"]  # Command arguments (optional)
    enabled: true        # Enable/disable without removing (optional)
    env:                 # Environment variables (optional)
      KEY: "value"
      SECRET: "${FROM_ENV}"  # Reference host env vars
```

### Environment Variable Substitution

Use `${VAR_NAME}` in any string value to reference the host environment:

```yaml
env:
  GITHUB_TOKEN: "${GITHUB_TOKEN}"     # From host env
  DATABASE_URL: "${DATABASE_URL}"
```

## 🔧 Using with AI Clients

Configure your AI client to connect to MCPHub instead of individual servers:

```json
{
  "mcpServers": {
    "mcphub": {
      "command": "mcphub",
      "args": ["/path/to/mcphub.yaml"]
    }
  }
}
```

All tools from all configured servers are now available through this single connection.

## 🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repo
2. Create your feature branch: `git checkout -b feat/amazing-feature`
3. Commit: `git commit -m 'Add amazing feature'`
4. Push: `git push origin feat/amazing-feature`
5. Open a Pull Request

### Development

```bash
git clone https://github.com/NeuZhou/mcphub.git
cd mcphub
npm install
npm run dev
```

## 📄 License

MIT © [Kang Zhou](https://github.com/NeuZhou)

---

<div align="center">

**🔱 One gateway to rule them all 🔱**

If MCPHub helps you, consider giving it a ⭐

</div>