> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcphub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start Guide

> Get MCPHub running in 5 minutes

## Installation

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

    ```bash theme={null}
    # Run with default configuration
    docker run -p 3000:3000 samanhappy/mcphub
    ```

    Or mount your custom configuration:

    ```bash theme={null}
    # 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 theme={null}
    # 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 theme={null}
    # 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 theme={null}
# 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 theme={null}
{
  "name": "fetch",
  "config": { "type": "stdio", "command": "uvx", "args": ["mcp-server-fetch"] }
}
```

Example SSE configuration:

```json theme={null}
{
  "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 theme={null}
    {
      "name": "fetch",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
    ```
  </Accordion>

  <Accordion title="Playwright Browser Automation">
    ```json theme={null}
    {
      "name": "playwright",
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    }
    ```
  </Accordion>

  <Accordion title="Amap Maps (with API key)">
    ```json theme={null}
    {
      "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 theme={null}
    {
      "name": "slack",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "your-bot-token",
        "SLACK_TEAM_ID": "your-team-id"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

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