mcphub/docs/getting-started.md

# Getting Started with MCP Hub

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Running the Server](#running-the-server)
5. [Connect Your AI Client](#connect-your-ai-client)
6. [Using MCP Tools](#using-mcp-tools)
7. [Docker Deployment](#docker-deployment)
8. [Coolify Deployment](#coolify-deployment)
9. [Next Steps](#next-steps)

---

## Prerequisites

### Required

- **Python 3.11+**: [Download Python](https://www.python.org/downloads/)
- **Git**: [Download Git](https://git-scm.com/downloads)

### Optional (for Docker deployment)

- **Docker**: [Download Docker Desktop](https://www.docker.com/products/docker-desktop)
- **Docker Compose**: Included with Docker Desktop

### WordPress Requirements

For each WordPress site you want to manage:

- WordPress 5.0+
- **Application Passwords** enabled (WordPress 5.6+)
- **WooCommerce** 3.0+ (if using WooCommerce tools)
- **Rank Math** or **Yoast SEO** (if using SEO tools)
- HTTPS enabled (recommended)

---

## Installation

### Option 0: Use Hosted Version (No Setup Required)

The fastest way to try MCP Hub — no installation needed:

1. Visit **[mcp.example.com](https://mcp.example.com)**
2. Log in with **GitHub** or **Google**
3. Add your sites via the dashboard (**My Sites → Add Service**)
4. Go to **Connect** page to generate your AI client config
5. Copy-paste into Claude Desktop, VS Code, or Claude Code

Your personal MCP endpoint:
```
https://mcp.example.com/u/{your-user-id}/{alias}/mcp
```

**WordPress users:** Install the [Airano MCP SEO Bridge](https://wordpress.org/plugins/airano-mcp-bridge/) plugin for SEO tools, and create an [Application Password](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/) (Users → Profile) for authentication.

> If you prefer self-hosting, continue with the options below.

---

### Option 1: Docker (Recommended)

```bash
git clone https://github.com/airano-ir/mcphub.git
cd mcphub
cp env.example .env
# Edit .env — set MASTER_API_KEY and add your site credentials (see Configuration below)
docker compose up -d
```

After starting, see [Verify Installation](#verify-installation) below.

### Option 2: Docker Hub (No Clone)

```bash
# 1. Create a .env file (see Configuration section below)
# 2. Run:
docker run -d --name mcphub -p 8000:8000 --env-file .env airano/mcphub:latest
```

### Option 3: From Source

```bash
git clone https://github.com/airano-ir/mcphub.git
cd mcphub
pip install -e .
cp env.example .env
# Edit .env with your site credentials
python server.py --transport streamable-http --port 8000
```

### Option 4: Automated Setup Scripts

#### Linux/Mac

```bash
git clone https://github.com/airano-ir/mcphub.git
cd mcphub
chmod +x scripts/setup.sh
./scripts/setup.sh
```

#### Windows (PowerShell)

```powershell
git clone https://github.com/airano-ir/mcphub.git
cd mcphub
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.\scripts\setup.ps1
```

---

## Configuration

### Step 1: Generate WordPress Application Passwords

For each WordPress site:

1. Log in to WordPress admin
2. Navigate to: **Users > Your Profile**
3. Scroll to **Application Passwords** section
4. Enter name: `MCP Hub`
5. Click **Add New Application Password**
6. Copy the generated password (format: `xxxx xxxx xxxx xxxx xxxx xxxx`)

**Important**: Save this password immediately. You cannot retrieve it later.

### Step 2: Generate WooCommerce API Keys

If using WooCommerce tools:

1. Go to: **WooCommerce > Settings > Advanced > REST API**
2. Click **Add Key**
3. Fill in:
   - **Description**: `MCP Hub`
   - **User**: Select admin user
   - **Permissions**: `Read/Write`
4. Click **Generate API Key**
5. Copy **Consumer Key** and **Consumer Secret**

### Step 3: Configure Environment Variables

Edit the `.env` file with your credentials:

```bash
# ============================================
# Authentication (recommended — auto-generates temp key if omitted)
# ============================================
MASTER_API_KEY=your-secure-key-here

# ============================================
# WordPress Site
# ============================================
WORDPRESS_SITE1_URL=https://myblog.com
WORDPRESS_SITE1_USERNAME=admin
WORDPRESS_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
WORDPRESS_SITE1_ALIAS=myblog

# ============================================
# WooCommerce Store (separate plugin)
# ============================================
WOOCOMMERCE_STORE1_URL=https://mystore.com
WOOCOMMERCE_STORE1_CONSUMER_KEY=ck_xxxxx
WOOCOMMERCE_STORE1_CONSUMER_SECRET=cs_xxxxx
WOOCOMMERCE_STORE1_ALIAS=mystore

# ============================================
# Gitea Instance (optional)
# ============================================
GITEA_REPO1_URL=https://git.example.com
GITEA_REPO1_TOKEN=your_gitea_token
GITEA_REPO1_ALIAS=mygitea

# ============================================
# OAuth (required for Claude/ChatGPT auto-registration)
# ============================================
OAUTH_JWT_SECRET_KEY=your-jwt-secret
OAUTH_BASE_URL=https://your-server:8000

# ============================================
# Social Login (GitHub/Google OAuth — for hosted/multi-user)
# ============================================
GITHUB_CLIENT_ID=your-github-oauth-app-id
GITHUB_CLIENT_SECRET=your-github-oauth-app-secret
GOOGLE_CLIENT_ID=your-google-oauth-client-id
GOOGLE_CLIENT_SECRET=your-google-oauth-client-secret
PUBLIC_URL=https://your-server:8000

# ============================================
# Encryption (required for storing user site credentials)
# ============================================
# Generate: python -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode())"
ENCRYPTION_KEY=your-base64-encoded-32-byte-key

# ============================================
# Optional
# ============================================
LOG_LEVEL=INFO
RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_PER_HOUR=1000
RATE_LIMIT_PER_DAY=10000
```

### WordPress Plugin Requirements

Some tools require specific WordPress plugins or infrastructure:

| Tools | Requirement |
|-------|-------------|
| `wordpress_get_post_seo`, `wordpress_update_post_seo`, `wordpress_get_product_seo`, `wordpress_update_product_seo` | **Yoast SEO** or **RankMath** |
| `wordpress_wp_cache_*`, `wordpress_wp_db_*`, `wordpress_wp_plugin_*`, `wordpress_wp_theme_*`, `wordpress_wp_core_*`, `wordpress_wp_search_replace_dry_run` (15 tools) | Docker socket + `CONTAINER` env var |
| `wordpress_specialist_*` (51 tools — plugins, themes, users, options, cron, maintenance, page editing, site config + layout, db inspection, bulk fan-out) | **Airano MCP Bridge v2.18.0+** companion plugin (no Docker socket) |
| `woocommerce_*` | **WooCommerce** plugin (separate `WOOCOMMERCE_` config) |

### Docker Socket for WP-CLI

A subset of legacy `wordpress_*` tools (15 WP-CLI helpers under
`wordpress_wp_*`) require Docker socket access:

```yaml
services:
  mcphub:
    image: airano/mcphub:latest
    ports:
      - "8000:8000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      WORDPRESS_SITE1_URL: https://your-site.com
      WORDPRESS_SITE1_USERNAME: admin
      WORDPRESS_SITE1_APP_PASSWORD: xxxx xxxx xxxx xxxx
      WORDPRESS_SITE1_CONTAINER: wordpress-container-name
      WORDPRESS_SITE1_ALIAS: mysite
```

`wordpress_specialist_*` tools do **not** need Docker — they're served
through the Airano MCP Bridge companion plugin via REST. Install
`wordpress-plugin/airano-mcp-bridge.zip` on the WordPress site and use
an Application Password for a `manage_options` user.

Without Docker socket:
- WP-CLI helpers (`wordpress_wp_*`) return "not available" errors
- All REST API tools (bulk operations, content management,
  `wordpress_specialist_*`) work normally

### Site Configuration

Sites are managed via the web dashboard. After starting the server, open the dashboard to add sites.

Each plugin requires specific credentials (see below for reference).

#### WordPress
```env
WORDPRESS_SITE1_URL=https://your-site.com        # Required
WORDPRESS_SITE1_USERNAME=admin                     # Required
WORDPRESS_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx   # Required (WordPress Application Password)
WORDPRESS_SITE1_ALIAS=my-site                      # Recommended
WORDPRESS_SITE1_CONTAINER=wp-container             # Optional (for WP-CLI)
```

#### WooCommerce
```env
WOOCOMMERCE_SITE1_URL=https://your-site.com       # Required
WOOCOMMERCE_SITE1_CONSUMER_KEY=ck_xxx             # Required
WOOCOMMERCE_SITE1_CONSUMER_SECRET=cs_xxx          # Required
WOOCOMMERCE_SITE1_ALIAS=my-shop                   # Recommended
```

#### WordPress Advanced
```env
WORDPRESS_ADVANCED_SITE1_URL=https://your-site.com         # Required
WORDPRESS_ADVANCED_SITE1_USERNAME=admin                     # Required
WORDPRESS_ADVANCED_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx   # Required
WORDPRESS_ADVANCED_SITE1_CONTAINER=wp-container             # Required (for WP-CLI tools)
WORDPRESS_ADVANCED_SITE1_ALIAS=my-site-admin                # Recommended
```

#### Gitea
```env
GITEA_SITE1_URL=https://gitea.example.com         # Required
GITEA_SITE1_TOKEN=your-access-token                # Required
GITEA_SITE1_ALIAS=my-gitea                         # Recommended
```

#### n8n
```env
N8N_SITE1_URL=https://n8n.example.com             # Required
N8N_SITE1_API_KEY=your-api-key                     # Required
N8N_SITE1_ALIAS=my-n8n                             # Recommended
```

#### Supabase
```env
SUPABASE_SITE1_URL=https://your-project.supabase.co   # Required
SUPABASE_SITE1_API_KEY=your-service-role-key           # Required
SUPABASE_SITE1_ALIAS=my-supabase                       # Recommended
```

#### OpenPanel
```env
OPENPANEL_SITE1_URL=https://openpanel.example.com  # Required
OPENPANEL_SITE1_CLIENT_ID=your-client-id           # Required
OPENPANEL_SITE1_CLIENT_SECRET=your-client-secret   # Required
OPENPANEL_SITE1_ALIAS=my-analytics                 # Recommended
```

#### Appwrite
```env
APPWRITE_SITE1_URL=https://appwrite.example.com   # Required
APPWRITE_SITE1_API_KEY=your-api-key                # Required
APPWRITE_SITE1_PROJECT_ID=your-project-id          # Required
APPWRITE_SITE1_ALIAS=my-appwrite                   # Recommended
```

#### Directus
```env
DIRECTUS_SITE1_URL=https://directus.example.com   # Required
DIRECTUS_SITE1_TOKEN=your-admin-token              # Required
DIRECTUS_SITE1_ALIAS=my-directus                   # Recommended
```

> **Note:** Use `APP_PASSWORD` (WordPress Application Password), not `PASSWORD`.

### Configuration Tips

- **Site Aliases**: Use friendly names like `myblog`, `mystore`, or `mygitea`
- **Separate plugins**: WordPress and WooCommerce are separate plugins with separate env var prefixes
- **Testing**: Start with one site, verify it works, then add more
- **Security**: Never commit `.env` file to git

---

## Running the Server

### Streamable HTTP Transport (for remote AI clients)

```bash
python server.py --transport streamable-http --port 8000
```

### Stdio Transport (for Claude Desktop local)

```bash
python server.py
```

### Verify Installation

After starting (via Docker or locally), wait ~30 seconds for the server to initialize, then:

**1. Check health:**

```bash
curl http://localhost:8000/health
# Expected: {"status": "ok", "tools_loaded": 565, ...}
```

**2. Open the web dashboard:**

Open **http://localhost:8000/dashboard** in your browser. Log in with your `MASTER_API_KEY` or via **GitHub/Google OAuth** (if configured).

The dashboard lets you:
- View all connected sites and their health status
- **Add, edit, delete, and test sites** via the My Sites page (OAuth users)
- Create and manage per-project API keys
- **Generate AI client configs** on the Connect page (with correct transport type per client)
- View audit logs and monitor rate limits
- **Per-user MCP endpoints**: OAuth users get personal endpoints at `/u/{user_id}/{alias}/mcp` with `mhu_` API keys

**3. Check container status (Docker only):**

```bash
docker compose ps
# Look for Status: "Up (healthy)"
# Note: Health check starts after 40 seconds — "starting" is normal initially

# View logs if something is wrong:
docker compose logs -f mcphub
```

**4. Troubleshooting:**

| Problem | Solution |
|---------|----------|
| Container exits immediately | Check logs: `docker compose logs mcphub` |
| Port 8000 already in use | Change port in docker-compose.yaml: `"8001:8000"` |
| Health check shows "unhealthy" | Wait 60 seconds, then check logs for startup errors |
| Dashboard login fails | Make sure you're using the `MASTER_API_KEY` value from your `.env` |
| Sites not showing up | Add sites via the web dashboard, then check the connect page |

---

## Connect Your AI Client

All requests require **Bearer token** authentication via the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

> `X-API-Key` header and query parameter auth are **not** supported.

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcphub-wordpress": {
      "type": "streamableHttp",
      "url": "http://your-server:8000/wordpress/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MASTER_API_KEY"
      }
    }
  }
}
```

### Claude Code

Add to `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "mcphub-wordpress": {
      "type": "http",
      "url": "http://your-server:8000/wordpress/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MASTER_API_KEY"
      }
    }
  }
}
```

### Cursor

Go to **Settings > MCP Servers > Add Server**:

- **Name**: MCP Hub WordPress
- **URL**: `http://your-server:8000/wordpress/mcp`
- **Headers**: `Authorization: Bearer YOUR_MASTER_API_KEY`

### VS Code + Copilot

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "mcphub-wordpress": {
      "type": "http",
      "url": "http://your-server:8000/wordpress/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MASTER_API_KEY"
      }
    }
  }
}
```

### ChatGPT (Remote MCP)

MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can auto-register as an OAuth client:

1. Deploy MCP Hub with `OAUTH_BASE_URL` set
2. In ChatGPT, add MCP server: `https://your-server:8000/mcp`
3. ChatGPT auto-discovers OAuth metadata and registers

> **Important**: Use `"type": "streamableHttp"` for Claude Desktop and `"type": "http"` for VS Code/Claude Code. Using `"type": "sse"` will cause `400 Bad Request` errors.

---

## Using MCP Tools

### 565 Tools Across 9 Plugins

| Plugin | Tools | Env Prefix |
|--------|-------|------------|
| WordPress | 67 | `WORDPRESS_` |
| WooCommerce | 28 | `WOOCOMMERCE_` |
| WordPress Advanced | 22 | `WORDPRESS_ADVANCED_` |
| Gitea | 56 | `GITEA_` |
| n8n | 56 | `N8N_` |
| Supabase | 70 | `SUPABASE_` |
| OpenPanel | 42 | `OPENPANEL_` |
| Appwrite | 100 | `APPWRITE_` |
| Directus | 100 | `DIRECTUS_` |
| System | 24 | (no config needed) |

### Unified Tool Pattern

All tools use a `site` parameter to select which site to operate on:

```python
wordpress_list_posts(site="myblog", per_page=10, status="publish")
wordpress_create_post(site="myblog", title="Hello", content="World")
woocommerce_list_products(site="mystore")
gitea_list_repos(site="mygitea")
```

The `site` parameter accepts either a **site_id** (e.g., `site1`) or an **alias** (e.g., `myblog`).

### Multi-Endpoint Architecture

Use the most specific endpoint for your use case to minimize token usage:

| Endpoint | Use Case | Tools | `site` param? |
|----------|----------|------:|:-------------:|
| `/project/{alias}/mcp` | Single-site workflow | 22-100 | No (pre-scoped) |
| `/{plugin}/mcp` | Multi-site management | 23-101 | Yes |
| `/system/mcp` | System administration | 24 | N/A |
| `/mcp` | Admin & discovery only | 565 | Yes |

> **Recommendation**: Always use the most specific endpoint. Using `/mcp` (565 tools) wastes context tokens and degrades AI response quality.

**Available plugin endpoints:**

| Endpoint | Plugin | Tools |
|----------|--------|------:|
| `/wordpress/mcp` | WordPress | 67 |
| `/woocommerce/mcp` | WooCommerce | 28 |
| `/wordpress-specialist/mcp` | WordPress Specialist | 51 |
| `/gitea/mcp` | Gitea | 56 |
| `/n8n/mcp` | n8n | 56 |
| `/supabase/mcp` | Supabase | 70 |
| `/openpanel/mcp` | OpenPanel | 42 |
| `/appwrite/mcp` | Appwrite | 100 |
| `/directus/mcp` | Directus | 100 |
| `/system/mcp` | System Management | 24 |

**Plugin endpoint vs Project endpoint:**

| Feature | Plugin (`/wordpress/mcp`) | Project (`/project/{alias}/mcp`) |
|---------|:------------------------:|:-------------------------------:|
| `list_sites` tool | Yes | No |
| `site` parameter needed | Yes | No (pre-scoped) |
| Tool count | N + 1 (includes `list_sites`) | N |
| Multi-site support | Yes | No (single site) |

---

## Docker Deployment

### Quick Start

```bash
docker compose up -d
```

After starting, verify the installation:

```bash
curl http://localhost:8000/health          # server health
open http://localhost:8000/dashboard        # web dashboard
```

See [Verify Installation](#verify-installation) for detailed steps.

### Docker Commands

```bash
# View logs
docker compose logs -f mcphub

# Check status (look for "healthy")
docker compose ps

# Restart (needed after .env changes)
docker compose restart

# Stop
docker compose down

# Rebuild (after code changes)
docker compose up --build -d
```

### Adding Sites After Startup

1. Edit your `.env` file to add new site credentials
2. Restart the container: `docker compose restart`
3. Verify: `curl http://localhost:8000/health` — check that tools are loaded
4. The dashboard at http://localhost:8000/dashboard will show the new sites

---

## Coolify Deployment

### Step 1: Create New Resource

1. Log in to Coolify dashboard
2. Click **+ New Resource**
3. Select **Docker Compose**

### Step 2: Configure Repository

1. **Git Repository**: `https://github.com/airano-ir/mcphub.git`
2. **Branch**: `main`
3. **Build Pack**: `Docker Compose`

### Step 3: Configure Environment Variables

Add the required environment variables in Coolify's environment variable UI:

```
MASTER_API_KEY=your-secure-key-here
OAUTH_JWT_SECRET_KEY=your-jwt-secret
OAUTH_BASE_URL=https://your-domain.com
ENCRYPTION_KEY=your-base64-encryption-key
```

After deployment, add sites via the web dashboard at `https://your-domain.com/dashboard`.

### Step 4: Configure Health Check

- **Path**: `/health`
- **Port**: `8000`
- **Interval**: `30s`
- **Timeout**: `10s`
- **Retries**: `3`

### Step 5: Deploy

1. Click **Deploy**
2. Wait for build to complete
3. Check logs for successful startup

---

## Next Steps

1. **Explore the full tool list**: See the [README](../README.md) for all 565 tools
2. **Set up API keys**: [API Keys Guide](API_KEYS_GUIDE.md) for per-project access control
3. **Configure OAuth**: [OAuth Guide](OAUTH_GUIDE.md) for Claude/ChatGPT auto-registration
4. **Monitor health**: Use `check_all_projects_health` tool or visit the web dashboard
5. **Troubleshoot issues**: [Troubleshooting Guide](troubleshooting.md)

---