Quick Start Guide

Installation

Docker (Recommended)
Local Development
npm Package

The fastest way to get started with MCPHub is using Docker:

# Run with default configuration
docker run -p 3000:3000 samanhappy/mcphub

Or mount your custom configuration:

# Run with custom MCP settings
docker run -p 3000:3000 \
  -v $(pwd)/mcp_settings.json:/app/mcp_settings.json \
  samanhappy/mcphub

For development or customization:

# Clone the repository
git clone https://github.com/samanhappy/mcphub.git
cd mcphub

# Install dependencies
pnpm install

# Start development servers
pnpm dev

This starts both backend (port 3000) and frontend (port 5173) in development mode. The Vite dev server proxies API and MCP traffic to the backend. Local development uses admin / admin123 and stores writable settings in data/mcp_settings.dev.json.

Install MCPHub as a global package:

# Install globally
npm install -g @samanhappy/mcphub

# Run MCPHub
mcphub

Initial Setup

1. Access the Dashboard

Open your browser and navigate to:

http://localhost:3000

The default username is admin. For local development with pnpm dev, use admin123. Docker, npm package, and production starts do not include a default user; if no ADMIN_PASSWORD environment variable is set on first launch, a random password is generated and printed to the server logs. To pre-set the admin password:

# Via environment variable
ADMIN_PASSWORD=your-secure-password docker run -p 3000:3000 samanhappy/mcphub

Change the admin password after first login for security.

ADMIN_PASSWORD and the random password printed to the logs apply only the first time MCPHub starts with an empty users list. Once any user exists, the variable is ignored — manage passwords through the dashboard or PUT /api/users/:username afterwards. To force a fresh bootstrap, remove the users from mcp_settings.json (file mode) or the mcphub_user table (database mode) before restarting.

3. Configure Your First MCP Server

Click “Add Server” in the dashboard. The form supports four transport types — pick the one that matches the upstream server:

Type	When to use	Required fields
`stdio` (default)	The server runs as a local process you launch (`uvx`, `npx`, etc.).	`command`, optional `args` and `env`.
`sse`	The server is reachable over HTTP/SSE.	`url`, optional `headers`, `enableKeepAlive`, `keepAliveInterval`.
`streamable-http`	The server speaks MCP Streamable HTTP.	`url`, optional `headers`.
`openapi`	You want to expose an OpenAPI service as MCP tools.	`openapi.url` or `openapi.schema`.

Example stdio configuration:

{
  "name": "fetch",
  "config": { "type": "stdio", "command": "uvx", "args": ["mcp-server-fetch"] }
}

Example SSE configuration:

{
  "name": "amap",
  "config": { "type": "sse", "url": "https://mcp.amap.com/sse?key=YOUR_KEY" }
}

See MCP Settings for the complete field reference.

Basic Usage

Connecting AI Clients

Once your servers are configured, connect your AI clients using MCPHub endpoints:

All Servers
Specific Group
Individual Server
Smart Routing

Access all configured MCP servers: http://localhost:3000/mcp

Access servers in a specific group: http://localhost:3000/mcp/{groupName}

Access a single server: http://localhost:3000/mcp/{serverName}

Use AI-powered tool discovery: http://localhost:3000/mcp/$smart

Smart routing requires PostgreSQL with pgvector and an LLM provider (OpenAI or compatible) API key.

Example: Adding Popular MCP Servers

Here are some popular MCP servers you can add:

Web Fetch Server

{
  "name": "fetch",
  "command": "uvx",
  "args": ["mcp-server-fetch"]
}

Playwright Browser Automation

{
  "name": "playwright",
  "command": "npx",
  "args": ["@playwright/mcp@latest", "--headless"]
}

Amap Maps (with API key)

{
  "name": "amap",
  "command": "npx",
  "args": ["-y", "@amap/amap-maps-mcp-server"],
  "env": {
    "AMAP_MAPS_API_KEY": "your-api-key-here"
  }
}

Slack Integration

{
  "name": "slack",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-slack"],
  "env": {
    "SLACK_BOT_TOKEN": "your-bot-token",
    "SLACK_TEAM_ID": "your-team-id"
  }
}

Next Steps

Server Management

Learn advanced server configuration and management

Group Management

Organize servers into logical groups

Smart Routing

Set up AI-powered tool discovery

API Reference

Explore the complete API documentation

Troubleshooting

Server won't start

Check if the MCP server command is accessible in your PATH - Verify environment variables are correctly set - Check MCPHub logs for detailed error messages

Can't connect from AI client

Ensure MCPHub is running on the correct port - Check firewall settings - Verify the endpoint URL format

Authentication issues

Verify credentials are correct - Check if JWT token is valid - Try clearing browser cache and cookies

Need more help? Join our Discord community for support!

Get Started

Core Features

Configuration

Development

Installation

Initial Setup

1. Access the Dashboard

3. Configure Your First MCP Server

Basic Usage

Connecting AI Clients

Example: Adding Popular MCP Servers

Next Steps

Server Management

Group Management

Smart Routing

API Reference

Troubleshooting

​Installation

​Initial Setup

​1. Access the Dashboard

​2. Login

​3. Configure Your First MCP Server

​Basic Usage

​Connecting AI Clients

​Example: Adding Popular MCP Servers

​Next Steps

Server Management

Group Management

Smart Routing

API Reference

​Troubleshooting

Installation

Initial Setup

1. Access the Dashboard

2. Login

3. Configure Your First MCP Server

Basic Usage

Connecting AI Clients

Example: Adding Popular MCP Servers

Next Steps

Troubleshooting