---
title: 'Quick Start Guide'
description: 'Get MCPHub running in 5 minutes'
---

## Installation

<Tabs>
  <Tab title="Docker (Recommended)">
    The fastest way to get started with MCPHub is using Docker:

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

    Or mount your custom configuration:

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

  </Tab>
  <Tab title="Local Development">
    For development or customization:

    ```bash
    # 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.

  </Tab>
  <Tab title="npm Package">
    Install MCPHub as a global package:

    ```bash
    # Install globally
    npm install -g @samanhappy/mcphub

    # Run MCPHub
    mcphub
    ```

  </Tab>
</Tabs>

## Initial Setup

### 1. Access the Dashboard

Open your browser and navigate to:

```
http://localhost:3000
```

### 2. Login

The default username is `admin`. On first launch, if no `ADMIN_PASSWORD` environment variable is set, a random password is generated and printed to the server logs.

To pre-set the admin password:

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

<Warning>Change the admin password after first login for security.</Warning>

<Note>
  `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.
</Note>

### 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:

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

Example SSE configuration:

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

See [MCP Settings](/configuration/mcp-settings) for the complete field reference.

## Basic Usage

### Connecting AI Clients

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

<Tabs>
  <Tab title="All Servers">
    Access all configured MCP servers: ``` http://localhost:3000/mcp ```
  </Tab>
  <Tab title="Specific Group">
    Access servers in a specific group: ``` http://localhost:3000/mcp/{groupName} ```
  </Tab>
  <Tab title="Individual Server">
    Access a single server: ``` http://localhost:3000/mcp/{serverName} ```
  </Tab>
  <Tab title="Smart Routing">
    Use AI-powered tool discovery: ``` http://localhost:3000/mcp/$smart ```
    <Info>Smart routing requires PostgreSQL with pgvector and an LLM provider (OpenAI or compatible) API key.</Info>
  </Tab>
</Tabs>

### Example: Adding Popular MCP Servers

Here are some popular MCP servers you can add:

<AccordionGroup>
  <Accordion title="Web Fetch Server">
    ```json
    {
      "name": "fetch",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
    ```
  </Accordion>
  
  <Accordion title="Playwright Browser Automation">
    ```json
    {
      "name": "playwright",
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    }
    ```
  </Accordion>
  
  <Accordion title="Amap Maps (with API key)">
    ```json
    {
      "name": "amap",
      "command": "npx",
      "args": ["-y", "@amap/amap-maps-mcp-server"],
      "env": {
        "AMAP_MAPS_API_KEY": "your-api-key-here"
      }
    }
    ```
  </Accordion>
  
  <Accordion title="Slack Integration">
    ```json
    {
      "name": "slack",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "your-bot-token",
        "SLACK_TEAM_ID": "your-team-id"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

{/* ## Verification

Test your setup by making a simple request:

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
```

You should receive a list of available tools from your configured MCP servers. */}

## Next Steps

<CardGroup cols={2}>
  <Card title="Server Management" icon="server" href="/features/server-management">
    Learn advanced server configuration and management
  </Card>
  <Card title="Group Management" icon="users" href="/features/group-management">
    Organize servers into logical groups
  </Card>
  <Card title="Smart Routing" icon="route" href="/features/smart-routing">
    Set up AI-powered tool discovery
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the complete API documentation
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Can't connect from AI client">
    - Ensure MCPHub is running on the correct port - Check firewall settings - Verify the endpoint
    URL format
  </Accordion>

  <Accordion title="Authentication issues">
    - Verify credentials are correct - Check if JWT token is valid - Try clearing browser cache and
    cookies
  </Accordion>
</AccordionGroup>

Need more help? Join our [Discord community](https://discord.gg/c8GKyzyFF) for support!
