Skip to content
Back to search

mcphub

Self-hosted MCP gateway and control plane for connecting, controlling, and operating MCP servers.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/samanhappy/mcphub with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/samanhappy/mcphub'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/samanhappy--mcphub/badge.svg)](/listings/samanhappy--mcphub)

HTML

<a href="/listings/samanhappy--mcphub"><img src="/api/listings/samanhappy--mcphub/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- **Docker** (recommended) — the fastest way to run MCPHub; all commands below use it - **Node.js** `>=20.0.0` and **pnpm** `10.12.4` — only needed to run from source or develop locally (see [Local Development](#local-development))

Start with Docker

docker run -p 3000:3000 -v ./data:/app/data samanhappy/mcphub

Open `http://localhost:3000` and log in with username `admin`. On first launch, if no `ADMIN_PASSWORD` environment variable is set, a random password is generated and printed to the server logs.

Settings, users, and credential bindings persist in `./data` by default.

Want your own servers? Before the first launch, create `data/mcp_settings.json` (see [Configuration](#configuration)). After launch, add servers in the dashboard or edit the existing file and restart MCPHub.

Configuration

Create `data/mcp_settings.json` before the first launch:

{
  "mcpServers": {
    "time": {
      "command": "npx",
      "args": ["-y", "time-mcp"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

📖 See [Configuration Guide](https://docs.mcphub.app/configuration/mcp-settings) for full options including OAuth, environment variables, and more.

Docker Deployment

See [Start with Docker](#start-with-docker) for the copy-paste command. Keep `./data` mounted so settings, users, and credential bindings survive container recreation.

Two image variants are published under `samanhappy/mcphub`:

- **`latest`** — the default image. Includes Node.js/pnpm, Python, uv/uvx, Git, and build tools. Covers most MCP servers. - **`latest-full`** — the extended image. Adds Rust toolchain (Cargo/rustc), Docker Engine, and Playwright browsers (Chrome + Firefox, amd64 only). Use this for Rust-based servers or container-in-container workflows. Larger download.

See [Docker Setup](https://docs.mcphub.app/configuration/docker-setup) for build options and Docker-in-Docker configuration.

Access Dashboard

Open `http://localhost:3000` (see [Start with Docker](#start-with-docker) for login details). You can also pre-set the password:

# Docker: set admin password via environment variable
docker run -p 3000:3000 -v ./data:/app/data -e ADMIN_PASSWORD=your-secure-password samanhappy/mcphub

> **Tip:** Change the admin password after first login for security.

> **Headless mode:** Set `DISABLE_WEB=true` to skip serving the bundled dashboard UI and run MCPHub with only the backend/API and MCP endpoints. This is useful when you want to manage servers directly from `mcp_settings.json`.

Connect AI Clients

Connect AI clients (Claude Desktop, Cursor, etc.) via:

http://localhost:3000/mcp           # All servers
http://localhost:3000/mcp/{group}   # Specific group
http://localhost:3000/mcp/{server}  # Specific server
http://localhost:3000/mcp/$smart    # Smart routing
http://localhost:3000/mcp/$smart/{group}  # Smart routing within group

> **Security note**: MCP endpoints require authentication by default to prevent accidental exposure. To allow unauthenticated MCP access, disable **Enable Bearer Authentication** in the Keys section. **Skip Authentication** only affects dashboard login. Use only in trusted environments.

📖 See [API Reference](https://docs.mcphub.app/api-reference) for detailed endpoint documentation.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 214 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCPHub
  2. > An open-source, self-hosted MCP gateway and control plane for connecting, controlling, and operating MCP servers.
  3. [![CI](https://github.com/samanhappy/mcphub/actions/workflows/ci.yml/badge.svg)](https://github.com/samanhappy/mcphub/actions/workflows/ci.yml)
  4. [![npm version](https://img.shields.io/npm/v/@samanhappy/mcphub)](https://www.npmjs.com/package/@samanhappy/mcphub)
  5. [![Docker pulls](https://img.shields.io/docker/pulls/samanhappy/mcphub)](https://hub.docker.com/r/samanhappy/mcphub)
  6. [![License](https://img.shields.io/github/license/samanhappy/mcphub)](LICENSE)
  7. [![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/2BJehJZVH5)
  8. [![GitHub stars](https://img.shields.io/github/stars/samanhappy/mcphub?style=social)](https://github.com/samanhappy/mcphub/stargazers)
  9. English | [Français](README.fr.md) | [中文版](README.zh.md)
  10. MCPHub provides a unified control point between AI clients and MCP servers. Connect local and remote MCP servers once, organize and route their capabilities through stable endpoints, control access with authentication, scoped credentials, and per-user visibility, and operate everything with centralized logs, activity tracking, and health monitoring.
  11. It works with MCP clients such as Claude Code, Cursor, Cherry Studio, OpenWebUI, and other MCP-compatible applications.
  12. ![Dashboard Preview](assets/dashboard.png)
  13. ## 🌐 Website, Demo & Docs
  14. - **Website**: [mcphub.app](https://www.mcphub.app/)
  15. - **Documentation**: [docs.mcphub.app](https://docs.mcphub.app/)
  16. - **Demo Environment**: [demo.mcphub.app](https://demo.mcphub.app/)
  17. ## 🚀 Features
  18. ### Connect once, expose everywhere
  19. - **Smart Routing** ⭐ - AI-powered tool discovery using vector semantic search ([Learn more](https://docs.mcphub.app/features/smart-routing))
  20. - **Unified MCP Gateway** - Expose all connected servers through stable MCP endpoints, including routes for groups and individual servers
  21. - **Server Aliases and Routing** - Define aliases and route clients to all servers, specific groups, individual servers, or smart routing
  22. - **SSE / Streamable HTTP / stdio Support** - Connect local and remote MCP servers over the supported transports
  23. - **File Staging** - Let stdio tools accept an uploaded copy of a client file or write a result the hub serves as a one-time download ([Learn more](docs/features/file-staging.mdx))
  24. - **Hot-Swappable Config** - Add, remove, or update servers without downtime
  25. ### Control access and credentials
  26. - **Per-user Credentials** ⭐ - Bind personal keys to one shared server, with encrypted storage and isolated stdio runtimes ([Learn more](docs/features/per-user-credentials.mdx))
  27. - **Authentication and Access Control** - Use OAuth 2.0, bearer keys, passkeys, and server or group visibility controls to manage access
  28. - **OAuth 2.0 Support** ⭐ - Both client and server modes for secure authentication ([Learn more](https://docs.mcphub.app/features/oauth))
  29. - **Social Login** - Seamless GitHub and Google login support with Better Auth integration (requires Database Mode)
  30. - **Server and Group Management** - Organize servers into groups, manage visibility, and control Tool, Prompt, and Resource exposure
  31. ### Operate with confidence
  32. - **Logs and Observability** - Inspect tool-call activity, request status, latency, and server logs
  33. - **Health Checks** - Monitor connection health and server status from one place
  34. - **Web Dashboard** - Manage server configuration and runtime operations from a browser
  35. - **MCP Apps Proxy** - Transparently forward interactive MCP Apps on single-server routes ([Learn more](https://docs.mcphub.app/features/mcp-apps))
  36. - **Tool Result Compression** - Transparently reduce large text tool outputs before they reach clients
  37. - **Database Mode** - Store configuration in PostgreSQL for production environments ([Learn more](https://docs.mcphub.app/configuration/database-configuration))
  38. - **Multiple Replicas** - Share PostgreSQL configuration with explicit session affinity and reconnect boundaries ([Deployment guide](https://docs.mcphub.app/configuration/replicas))
  39. - **Docker-Ready** - Deploy instantly with containerized setup
  40. ## 🔧 Quick Start
  41. ### Prerequisites
  42. - **Docker** (recommended) — the fastest way to run MCPHub; all commands below use it
  43. - **Node.js** `>=22.0.0` and **pnpm** `10.12.4` — only needed to run from source or develop locally (see [Local Development](#local-development))
  44. ### Start with Docker
  45. ```bash
  46. docker run -p 3000:3000 -v ./data:/app/data samanhappy/mcphub
  47. ```
  48. Open `http://localhost:3000` and log in with username `admin`. On first launch, if no `ADMIN_PASSWORD` environment variable is set, a random password is generated and printed to the server logs.
  49. Settings, users, and credential bindings persist in `./data` by default.
  50. Want your own servers? Before the first launch, create `data/mcp_settings.json` (see [Configuration](#configuration)). After launch, add servers in the dashboard or edit the existing file and restart MCPHub.
  51. ### Configuration
  52. Create `data/mcp_settings.json` before the first launch:
  53. ```json
  54. {
  55. "mcpServers": {
  56. "time": {
  57. "command": "npx",
  58. "args": ["-y", "time-mcp"]
  59. },
  60. "fetch": {
  61. "command": "uvx",
  62. "args": ["mcp-server-fetch"]
  63. }
  64. }
  65. }
  66. ```
  67. 📖 See [Configuration Guide](https://docs.mcphub.app/configuration/mcp-settings) for full options including OAuth, environment variables, and more.
  68. ### Docker Deployment
  69. See [Start with Docker](#start-with-docker) for the copy-paste command. Keep `./data` mounted so settings, users, and credential bindings survive container recreation.
  70. Two image variants are published under `samanhappy/mcphub`:
  71. - **`latest`** — the default image. Includes Node.js/pnpm, Python, uv/uvx, Git, and build tools. Covers most MCP servers.
  72. - **`latest-full`** — the extended image. Adds Rust toolchain (Cargo/rustc), Docker Engine, and Playwright browsers (Chrome + Firefox, amd64 only). Use this for Rust-based servers or container-in-container workflows. Larger download.
  73. See [Docker Setup](https://docs.mcphub.app/configuration/docker-setup) for build options and Docker-in-Docker configuration.
  74. ### One-Click Deploy
  75. <a href="https://repocloud.io/details/MCPHub/"><img src="https://d16t0pc4846x52.cloudfront.net/deploylobe.svg" alt="Deploy on RepoCloud" height="42"></a>
  76. <a href="https://railway.com/deploy/mcphub"><img src="https://railway.com/button.svg" alt="Deploy on Railway" height="42"></a>
  77. ### Upgrading deployments with personal credentials
  78. Database mode requires a persistent `MCPHUB_CREDENTIAL_ENCRYPTION_KEY` or an existing key file; it no longer generates a local key automatically. Before replacing a working container, back up its original key and preserve the same value in deployment secrets. A database backup alone cannot recover encrypted credentials if the key is lost. See the [Credential Key Upgrade and Recovery Guide](docs/configuration/credential-key-upgrade.mdx) for working deployments and recovery after a failed upgrade.
  79. ### Access Dashboard
  80. Open `http://localhost:3000` (see [Start with Docker](#start-with-docker) for login details). You can also pre-set the password:
  81. ```bash
  82. # Docker: set admin password via environment variable
  83. docker run -p 3000:3000 -v ./data:/app/data -e ADMIN_PASSWORD=your-secure-password samanhappy/mcphub
  84. ```
  85. > **Tip:** Change the admin password after first login for security.
  86. > **Headless mode:** Set `DISABLE_WEB=true` to skip serving the bundled dashboard UI and run MCPHub with only the backend/API and MCP endpoints. This is useful when you want to manage servers directly from `mcp_settings.json`.
  87. ### Connect AI Clients
  88. Connect AI clients (Claude Desktop, Cursor, etc.) via:
  89. ```
  90. http://localhost:3000/mcp # All servers
  91. http://localhost:3000/mcp/{group} # Specific group
  92. http://localhost:3000/mcp/{server} # Specific server
  93. http://localhost:3000/mcp/$smart # Smart routing
  94. http://localhost:3000/mcp/$smart/{group} # Smart routing within group
  95. ```
  96. Set `SMART_ROUTING_PATH=my_smart` to use `/mcp/my_smart` (and `/mcp/my_smart/{group}`) without `$`. Restart to apply; `/mcp/$smart` remains supported. Include `BASE_PATH` before `/mcp` when configured. The custom segment must not match an existing server name, group name or group ID.
  97. > **Security note**: MCP endpoints require authentication by default to prevent accidental exposure. To allow unauthenticated MCP access, disable **Enable Bearer Authentication** in the Keys section. **Skip Authentication** only affects dashboard login. Use only in trusted environments.
  98. 📖 See [API Reference](https://docs.mcphub.app/api-reference) for detailed endpoint documentation.
  99. ## 📚 Documentation
  100. | Topic | Description |
  101. | ------------------------------------------------------------------------------ | --------------------------------- |
  102. | [Quick Start](https://docs.mcphub.app/quickstart) | Get started in 5 minutes |
  103. | [Configuration](https://docs.mcphub.app/configuration/mcp-settings) | MCP server configuration options |
  104. | [Database Mode](https://docs.mcphub.app/configuration/database-configuration) | PostgreSQL setup for production |
  105. | [OAuth](https://docs.mcphub.app/features/oauth) | OAuth 2.0 client and server setup |
  106. | [Smart Routing](https://docs.mcphub.app/features/smart-routing) | AI-powered tool discovery |
  107. | [MCP Apps](https://docs.mcphub.app/features/mcp-apps) | Interactive Apps transparent proxy |
  108. | [CLI Guide](https://docs.mcphub.app/features/cli) | Manage and call the hub from a terminal |
  109. | [Docker Setup](https://docs.mcphub.app/configuration/docker-setup) | Docker deployment guide |
  110. ## 🧑‍💻 Local Development
  111. ```bash
  112. git clone https://github.com/samanhappy/mcphub.git
  113. cd mcphub
  114. pnpm install
  115. pnpm dev
  116. ```
  117. Local development uses `admin` / `admin123` and stores its writable settings copy at `data/mcp_settings.dev.json`, so the repository `mcp_settings.json` stays credential-free.
  118. > For Windows users, start backend and frontend separately: `pnpm backend:dev`, `pnpm frontend:dev`
  119. 📖 See [Development Guide](https://docs.mcphub.app/development) for detailed setup instructions.
  120. ## 🔍 Tech Stack
  121. - **Backend**: Node.js, Express, TypeScript (ESM)
  122. - **Frontend**: React, Vite, Tailwind CSS
  123. - **Storage**: file-based `mcp_settings.json` by default; PostgreSQL via TypeORM with pgvector for Smart Routing
  124. - **Auth**: JWT + bcrypt for local accounts, with optional passkeys (WebAuthn); bearer keys; built-in OAuth 2.0 server (`@node-oauth/oauth2-server`); optional Better Auth for GitHub/Google login
  125. - **Protocol**: Model Context Protocol SDK
  126. ## 🏢 Production Support
  127. Running MCPHub in production?
  128. Work directly with the maintainer on production architecture, OAuth/OIDC,
  129. identity and access control, credential management, audit, Kubernetes, and HA readiness.
  130. [Discuss a production pilot →](https://www.mcphub.app/pricing)
  131. ## 👥 Contributing
  132. Contributions welcome! See our [Discord community](https://discord.gg/2BJehJZVH5) for discussions and support.
  133. ## ❤️ Sponsor
  134. [![Sponsor samanhappy](https://img.shields.io/badge/Sponsor-samanhappy-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/samanhappy)
  135. [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/samanhappy)
  136. Chinese users can also support via WeChat Pay — see [中文版](README.zh.md).
  137. ## Acknowledgements
  138. - [AtomGit](https://atomgit.com/samanhappy/mcphub): Hosts MCPHub in China, making the project easier to access for users in mainland China.
  139. ## 🌟 Star History
  140. [![Star History Chart](https://star-history.dera.page/svg?repos=samanhappy/mcphub&type=Date)](https://star-history.dera.page/#samanhappy/mcphub&Date)
  141. ## 📄 License
  142. Licensed under the [Apache 2.0 License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.