390 lines
14 KiB
Markdown
390 lines
14 KiB
Markdown
<!-- mcp-name: io.github.airano-ir/mcphub -->
|
|
|
|
# MCP Hub
|
|
|
|
<div align="center">
|
|
|
|
**The AI-native management hub for WordPress, WooCommerce, and self-hosted services.**
|
|
|
|
Connect your sites, stores, repos, and databases — manage them all through Claude, ChatGPT, Cursor, or any MCP client.
|
|
|
|
[](https://github.com/airano-ir/mcphub/releases)
|
|
[](LICENSE)
|
|
[](https://www.python.org/)
|
|
[](https://pypi.org/project/mcphub-server/)
|
|
[](https://hub.docker.com/r/airano/mcphub)
|
|
[]()
|
|
[]()
|
|
[](https://github.com/airano-ir/mcphub/actions/workflows/ci.yml)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## Why MCP Hub?
|
|
|
|
WordPress powers 43% of the web. WooCommerce runs 36% of online stores. Yet **no MCP server existed** for managing them through AI — until now.
|
|
|
|
MCP Hub is the first MCP server that lets you manage WordPress, WooCommerce, and 7 other self-hosted services through any AI assistant. Instead of clicking through dashboards, just tell your AI what to do:
|
|
|
|
> *"Update the SEO meta description for all WooCommerce products that don't have one"*
|
|
>
|
|
> *"Create a new blog post about our Black Friday sale and schedule it for next Monday"*
|
|
>
|
|
> *"Check the health of all 12 WordPress sites and report any with slow response times"*
|
|
|
|
### What Makes MCP Hub Different
|
|
|
|
| Feature | ManageWP | MainWP | AI Content Plugins | **MCP Hub** |
|
|
|---------|----------|--------|---------------------|-------------|
|
|
| Multi-site management | Yes | Yes | No | **Yes** |
|
|
| AI agent integration | No | No | No | **Native (MCP)** |
|
|
| Full WordPress API | Dashboard | Dashboard | Content only | **67 tools** |
|
|
| WooCommerce management | No | Limited | No | **28 tools** |
|
|
| Git/CI management | No | No | No | **56 tools (Gitea)** |
|
|
| Automation workflows | No | No | No | **56 tools (n8n)** |
|
|
| Self-hosted | No | Yes | N/A | **Yes** |
|
|
| Open source | No | Core only | Varies | **Fully open** |
|
|
| Price | $0.70-8/site/mo | $29-79/yr | $19-79/mo | **Free** |
|
|
|
|
---
|
|
|
|
## 565 Tools Across 9 Plugins
|
|
|
|
| Plugin | Tools | What You Can Do |
|
|
|--------|-------|-----------------|
|
|
| **WordPress** | 67 | Posts, pages, media, users, menus, taxonomies, SEO (Rank Math/Yoast) |
|
|
| **WooCommerce** | 28 | Products, orders, customers, coupons, reports, shipping |
|
|
| **WordPress Advanced** | 22 | Database ops, bulk operations, WP-CLI, system management |
|
|
| **Gitea** | 56 | Repos, issues, pull requests, releases, webhooks, organizations |
|
|
| **n8n** | 56 | Workflows, executions, credentials, variables, audit |
|
|
| **Supabase** | 70 | Database, auth, storage, edge functions, realtime |
|
|
| **OpenPanel** | 42 | Events, export, insights, profiles, projects, system |
|
|
| **Appwrite** | 100 | Databases, auth, storage, functions, teams, messaging |
|
|
| **Directus** | 100 | Collections, items, users, files, flows, permissions |
|
|
| **System** | 24 | Health monitoring, API keys, OAuth management, audit |
|
|
| **Total** | **565** | Constant count — scales to unlimited sites |
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### 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, then add sites via the web dashboard
|
|
docker compose up -d
|
|
```
|
|
|
|
### Option 2: Docker Hub (No Clone)
|
|
|
|
```bash
|
|
# Create a .env file with MASTER_API_KEY (see "Configure Your Sites" below)
|
|
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 — set MASTER_API_KEY
|
|
python server.py --transport streamable-http --port 8000
|
|
```
|
|
|
|
### Verify It Works
|
|
|
|
After starting the server, wait ~30 seconds then:
|
|
|
|
```bash
|
|
# Check server health
|
|
curl http://localhost:8000/health
|
|
```
|
|
|
|
Open the **web dashboard** in your browser: **http://localhost:8000/dashboard**
|
|
|
|
You should see the login page. Log in with your `MASTER_API_KEY` or via **GitHub/Google OAuth** (if configured).
|
|
|
|
### Try It Now (No Setup Required)
|
|
|
|
**Don't want to self-host?** Use the hosted instance at **[mcp.example.com](https://mcp.example.com)**:
|
|
|
|
1. Log in with **GitHub** or **Google**
|
|
2. Add your sites via the dashboard (My Sites → Add Service)
|
|
3. Go to **Connect** page — generate config for your AI client
|
|
4. Copy-paste the config into Claude Desktop, VS Code, or Claude Code
|
|
|
|
Your personal MCP endpoint: `https://mcp.example.com/u/{your-user-id}/{alias}/mcp`
|
|
|
|
---
|
|
|
|
### Configure Your Sites
|
|
|
|
Sites are managed via the **web dashboard** — no environment variables needed.
|
|
|
|
1. Set `MASTER_API_KEY` in your `.env` file
|
|
2. Start the server and open the dashboard
|
|
3. Add sites with their credentials (URL, username, password/token)
|
|
|
|
```bash
|
|
# .env — only system configuration needed
|
|
MASTER_API_KEY=your-secure-key-here
|
|
```
|
|
|
|
<details>
|
|
<summary><b>Full Environment Variable Reference</b></summary>
|
|
|
|
**System Configuration:**
|
|
|
|
| Variable | Required | Default | Description |
|
|
|----------|----------|---------|-------------|
|
|
| `MASTER_API_KEY` | Recommended | Auto-generated | Master API key for admin access |
|
|
| `LOG_LEVEL` | No | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
|
|
| `ENCRYPTION_KEY` | For Live Platform | — | AES-256-GCM key for credential encryption |
|
|
| `OAUTH_JWT_SECRET_KEY` | For OAuth | — | JWT secret for ChatGPT auto-registration (not needed for Claude/Cursor) |
|
|
| `OAUTH_BASE_URL` | For OAuth | — | Public URL of your server (not needed for Claude/Cursor) |
|
|
|
|
> **OAuth** is only needed for ChatGPT Remote MCP auto-registration. For Claude Desktop, Claude Code, Cursor, and VS Code — just use `MASTER_API_KEY` with Bearer token auth.
|
|
|
|
**Plugin Credential Reference** — when adding sites via dashboard, you'll need:
|
|
|
|
| Plugin | Required Credentials | Notes |
|
|
|--------|---------------------|-------|
|
|
| WordPress | URL, Username, App Password | [How to create App Password](https://wordpress.org/documentation/article/application-passwords/) |
|
|
| WooCommerce | URL, Consumer Key, Consumer Secret | WooCommerce → Settings → Advanced → REST API |
|
|
| WordPress Advanced | URL, Username, App Password, Container | Container = Docker container name (for WP-CLI) |
|
|
| Gitea | URL, Token | Settings → Applications → Personal Access Token |
|
|
| n8n | URL, API Key | Settings → API → Create API Key |
|
|
| Supabase | URL, Service Role Key | Supabase Dashboard → Settings → API |
|
|
| OpenPanel | URL, Client ID, Client Secret | OpenPanel Dashboard → Project Settings |
|
|
| Appwrite | URL, API Key, Project ID | Appwrite Console → Settings → API Keys |
|
|
| Directus | URL, Static Token | Directus Admin → Settings |
|
|
|
|
</details>
|
|
|
|
### Connect Your AI Client
|
|
|
|
All MCP clients use **Bearer token** authentication: `Authorization: Bearer YOUR_API_KEY`
|
|
|
|
> Use a plugin-specific endpoint (e.g., `/wordpress/mcp`) instead of `/mcp` to reduce tool count and save tokens. See [Architecture](#architecture) below.
|
|
|
|
<details>
|
|
<summary><b>Claude Desktop</b></summary>
|
|
|
|
Add to `claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"mcphub-wordpress": {
|
|
"type": "streamableHttp",
|
|
"url": "http://your-server:8000/wordpress/mcp",
|
|
"headers": {
|
|
"Authorization": "Bearer YOUR_API_KEY"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>Claude Code</b></summary>
|
|
|
|
Add to `.mcp.json` in your project:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"mcphub-wordpress": {
|
|
"type": "http",
|
|
"url": "http://your-server:8000/wordpress/mcp",
|
|
"headers": {
|
|
"Authorization": "Bearer YOUR_API_KEY"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>Cursor</b></summary>
|
|
|
|
Go to **Settings > MCP Servers > Add Server**:
|
|
|
|
- **Name**: MCP Hub WordPress
|
|
- **URL**: `http://your-server:8000/wordpress/mcp`
|
|
- **Headers**: `Authorization: Bearer YOUR_API_KEY`
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>VS Code + Copilot</b></summary>
|
|
|
|
Add to `.vscode/mcp.json`:
|
|
|
|
```json
|
|
{
|
|
"servers": {
|
|
"mcphub-wordpress": {
|
|
"type": "http",
|
|
"url": "http://your-server:8000/wordpress/mcp",
|
|
"headers": {
|
|
"Authorization": "Bearer YOUR_API_KEY"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>ChatGPT (Remote MCP)</b></summary>
|
|
|
|
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
|
|
|
|
</details>
|
|
|
|
> **Transport types**: Use `"type": "streamableHttp"` for Claude Desktop and `"type": "http"` for VS Code/Claude Code. Using `"type": "sse"` will cause `400 Bad Request` errors.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
/mcp → Admin endpoint (all 565 tools)
|
|
/system/mcp → System tools only (24 tools)
|
|
/wordpress/mcp → WordPress tools (67 tools)
|
|
/woocommerce/mcp → WooCommerce tools (28 tools)
|
|
/wordpress-advanced/mcp → WordPress Advanced tools (22 tools)
|
|
/gitea/mcp → Gitea tools (56 tools)
|
|
/n8n/mcp → n8n tools (56 tools)
|
|
/supabase/mcp → Supabase tools (70 tools)
|
|
/openpanel/mcp → OpenPanel tools (42 tools)
|
|
/appwrite/mcp → Appwrite tools (100 tools)
|
|
/directus/mcp → Directus tools (100 tools)
|
|
/project/{alias}/mcp → Per-project endpoint (auto-injects site)
|
|
/u/{user_id}/{alias}/mcp → Per-user endpoint (hosted/OAuth users)
|
|
```
|
|
|
|
**Recommendation**: Use plugin-specific endpoints instead of `/mcp` (565 tools) to minimize token usage.
|
|
|
|
| Endpoint | Use Case | Tools |
|
|
|----------|----------|------:|
|
|
| `/u/{user_id}/{alias}/mcp` | Hosted users (OAuth login) | 22-100 |
|
|
| `/project/{alias}/mcp` | Single-site workflow (recommended) | 22-100 |
|
|
| `/{plugin}/mcp` | Multi-site management | 23-101 |
|
|
| `/mcp` | Admin & discovery only | 565 |
|
|
|
|
### Security
|
|
|
|
- **OAuth 2.1 + PKCE** (RFC 8414, 7591, 7636) with auto-registration for Claude/ChatGPT
|
|
- **Per-project API keys** with scoped permissions (read/write/admin)
|
|
- **Rate limiting**: 60/min, 1,000/hr, 10,000/day per client
|
|
- **GDPR-compliant audit logging** with automatic sensitive data filtering
|
|
- **Web dashboard** with real-time health monitoring (8 pages, EN/FA i18n)
|
|
|
|
> **Compatibility Note**: MCP Hub requires FastMCP 2.x (`>=2.14.0,<3.0.0`). FastMCP 3.0 introduced breaking changes and is not yet supported. If you install dependencies manually, ensure you don't upgrade to FastMCP 3.x.
|
|
|
|
### WordPress Plugin Requirements
|
|
|
|
Some MCP Hub tools require companion WordPress plugins:
|
|
|
|
| Tools | Requirement |
|
|
|-------|-------------|
|
|
| SEO tools (`wordpress_get_post_seo`, etc.) | [Airano MCP SEO Bridge](https://wordpress.org/plugins/airano-mcp-seo-bridge/) ([GitHub](wordpress-plugin/airano-mcp-seo-bridge/)) + Rank Math or Yoast SEO |
|
|
| WP-CLI tools (15 tools: `wp_cache_*`, `wp_db_*`, etc.) | Docker socket + `CONTAINER` config |
|
|
| WordPress Advanced database/system tools | Docker socket + `CONTAINER` config |
|
|
| OpenPanel analytics integration | [OpenPanel Self-Hosted](wordpress-plugin/openpanel-self-hosted/) ([Download ZIP](wordpress-plugin/openpanel-self-hosted.zip)) |
|
|
| WooCommerce tools | WooCommerce plugin installed on your WordPress site |
|
|
|
|
**Docker socket** is needed for WP-CLI and WordPress Advanced system tools. Add to your docker-compose:
|
|
|
|
```yaml
|
|
volumes:
|
|
- /var/run/docker.sock:/var/run/docker.sock:ro
|
|
```
|
|
|
|
Set the `container` field when adding a WordPress site in the dashboard. Without Docker socket, WP-CLI tools return "not available" but all REST API tools work normally.
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| Guide | Description |
|
|
|-------|-------------|
|
|
| [Getting Started](docs/getting-started.md) | Full setup walkthrough |
|
|
| [Architecture](docs/ARCHITECTURE.md) | System design and module reference |
|
|
| [API Keys Guide](docs/API_KEYS_GUIDE.md) | Per-project API key management |
|
|
| [OAuth Guide](docs/OAUTH_GUIDE.md) | OAuth 2.1 setup for Claude/ChatGPT |
|
|
| [Gitea Guide](docs/GITEA_GUIDE.md) | Gitea plugin configuration |
|
|
| [Deployment Guide](docs/DEPLOYMENT_GUIDE.md) | Docker and Coolify deployment |
|
|
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
|
|
| [Plugin Development](docs/PLUGIN_DEVELOPMENT.md) | Build your own plugin |
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install with dev dependencies
|
|
pip install -e ".[dev]"
|
|
|
|
# Run tests (481 tests)
|
|
pytest
|
|
|
|
# Format and lint
|
|
black . && ruff check --fix .
|
|
|
|
# Run server locally
|
|
python server.py --transport streamable-http --port 8000
|
|
```
|
|
|
|
---
|
|
|
|
## Support This Project
|
|
|
|
MCP Hub is free and open-source. Development is funded by community donations.
|
|
|
|
[**Donate with Crypto (NOWPayments)**](https://nowpayments.io/donation/airano) — Global, no geographic restrictions.
|
|
|
|
| Goal | Monthly | Enables |
|
|
|------|---------|---------|
|
|
| Infrastructure | $50/mo | Demo hosting, CI/CD, domain |
|
|
| Part-time maintenance | $500/mo | Updates, security patches, issue triage |
|
|
| Active development | $2,000/mo | New plugins, features, community support |
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
|
|
**Priority areas:**
|
|
- New plugin development
|
|
- Client setup guides
|
|
- Workflow templates and examples
|
|
- Test coverage expansion
|
|
- Translations (i18n)
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT License. See [LICENSE](LICENSE).
|
|
|
|
---
|