# 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 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
# ============================================
# 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:
```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_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
```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": 596, ...}
```
**2. Open the web dashboard:**
Open **http://localhost:8000/dashboard** in your browser. Log in with your `MASTER_API_KEY`.
The dashboard lets you:
- View all connected sites and their health status
- Create and manage per-project API keys
- View audit logs
- Monitor rate limits
**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 | 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`:
```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
### 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:
```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 | 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
```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 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](../README.md) for all 596 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)
---
