mcphub/docs/getting-started.md

Getting Started with MCP Hub

---

Table of Contents

1. Prerequisites
2. Installation
3. Configuration
4. Running the Server
5. Connect Your AI Client
6. Using MCP Tools
7. Docker Deployment
8. Coolify Deployment
9. Next Steps

---

Prerequisites

Required

• Python 3.11+: Download Python
• Git: Download Git

Optional (for Docker deployment)

• Docker: Download 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.palebluedot.live
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.palebluedot.live/u/{your-user-id}/{alias}/mcp

WordPress users: Install the Airano MCP SEO Bridge plugin for SEO tools, and create an Application Password (Users → Profile) for authentication.

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

---

Option 1: Docker (Recommended)

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 below.

Option 2: Docker Hub (No Clone)

# 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

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

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

Windows (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:

# ============================================
# 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_advanced_* database/system tools	Docker socket + CONTAINER env var
woocommerce_*	WooCommerce plugin (separate WOOCOMMERCE_ config)

Docker Socket for WP-CLI / WordPress Advanced

WP-CLI and WordPress Advanced system tools require Docker socket access:

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_ADVANCED_SITE1_URL: https://your-site.com
      WORDPRESS_ADVANCED_SITE1_USERNAME: admin
      WORDPRESS_ADVANCED_SITE1_APP_PASSWORD: xxxx xxxx xxxx xxxx
      WORDPRESS_ADVANCED_SITE1_CONTAINER: wordpress-container-name
      WORDPRESS_ADVANCED_SITE1_ALIAS: mysite-admin

Without Docker socket:

• WP-CLI tools return "not available" errors
• WordPress Advanced database/system tools are unavailable
• All REST API tools (bulk operations, content management) work normally

Environment Variable Reference

All site configuration follows the pattern: {PLUGIN_TYPE}_{SITE_ID}_{CONFIG_KEY}=value

• SITE_ID can be any alphanumeric identifier (e.g., SITE1, PROD, MYBLOG)
• Multiple sites: change SITE1 to SITE2, SITE3, etc.

WordPress

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

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

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

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

n8n

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

Supabase

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

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

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

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)

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

Stdio Transport (for Claude Desktop local)

python server.py

Verify Installation

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

1. Check health:

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

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

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	Restart after adding new env vars: docker compose restart

---

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:

{
  "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:

{
  "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:

{
  "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

596 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	73	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:

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	596	Yes

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

Available plugin endpoints:

Endpoint	Plugin	Tools
/wordpress/mcp	WordPress	67
/woocommerce/mcp	WooCommerce	28
/wordpress-advanced/mcp	WordPress Advanced	22
/gitea/mcp	Gitea	56
/n8n/mcp	n8n	56
/supabase/mcp	Supabase	70
/openpanel/mcp	OpenPanel	73
/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

docker compose up -d

After starting, verify the installation:

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

See Verify Installation for detailed steps.

Docker Commands

# 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 all 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
WORDPRESS_SITE1_URL=https://example.com
WORDPRESS_SITE1_USERNAME=admin
WORDPRESS_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx

The server auto-discovers all WORDPRESS_*, WOOCOMMERCE_*, GITEA_*, and other plugin environment variables at startup.

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 for all 596 tools
2. Set up API keys: API Keys Guide for per-project access control
3. Configure OAuth: OAuth Guide for Claude/ChatGPT auto-registration
4. Monitor health: Use check_all_projects_health tool or visit the web dashboard
5. Troubleshoot issues: Troubleshooting Guide

---