English | 中文

MCPHub

🚀 An MCP Tool Service Platform - One Connection, Infinite Possibilities for AI Agents

Key Features • Quick Start • Feature Details • API Documentation • Development Guide

---

📸 System Screenshots

Login Interface

Default credentials: username admin, password admin123

Module Management Interface

Manage all MCP modules with support for loading, unloading, and reloading operations

Tool Details & Control

Enable/disable each tool individually, edit tool descriptions in real-time

Proxy Server Management

Proxy existing MCP Servers without modification

Usage Statistics Dashboard

Visualize tool call counts, success rates, and response times

AI Code Generation

Generate MCP plugin code through natural language conversation

---

🎯 What is This?

MCPHub is a tool service platform based on the MCP (Model Context Protocol). It addresses a pain point in current AI Agent systems:

Each MCP Server needs to be configured separately on the client side. As the number of tools increases, configuration management becomes chaotic.

MCPHub's Solution:

┌─────────────────────────────────────────────────────────────────┐
│                    Before: Scattered Configuration              │
│  Claude/Cursor needs to configure dozens of MCP Server addresses│
│  - mcp-server-filesystem                                        │
│  - mcp-server-github                                            │
│  - mcp-server-postgres                                          │
│  - mcp-server-python                                            │
│  - ... (configuration explosion)                                │
└─────────────────────────────────────────────────────────────────┘
                              ⬇️
┌─────────────────────────────────────────────────────────────────────┐
│                    After: Unified Entry Point                       
│  Claude/Cursor only needs to configure one address                  
│  { "mcpServers": { "mcp-hub": { "url": "http://host:6081/mcp" } } } 
│                                                                     
│  MCP Hub automatically aggregates all tools, providing:             
│  ✅ Centralized tool management                                     
│  ✅ Hot-pluggable enable/disable                                    
│  ✅ Unified monitoring and statistics                               
└─────────────────────────────────────────────────────────────────────┘

---

✨ Key Features

1️⃣ One Address, Infinite Tools

AI Agent clients only need to configure one MCP Server address to access all tools on the platform. Whether built-in tools, custom plugins, or proxied third-party MCP Servers, they are all transparent to clients.

2️⃣ Hot-Pluggable Tool Management

• Module-level Management: Load, unload, and reload modules without restarting the service
• Tool-level Control: Individual tools can be enabled/disabled independently
• Hot Configuration Updates: Tool description changes take effect immediately without restart

3️⃣ Proxy Existing MCP Servers

Already have MCP Servers? No modification needed - just configure a proxy to integrate:

{
  "name": "my-existing-server",
  "url": "http://existing-server:8080/mcp",
  "transport": "streamable-http"
}

The platform automatically discovers and transparently proxies all tools from that server.

4️⃣ AI-Powered MCP Plugin Generation

Built-in AI code generation feature - generate compliant MCP module code through natural language conversation:

User: Help me create a weather query tool
AI: Generated t_weather module with get_current_weather and get_forecast tools...

Everyone can become an MCP tool developer!

5️⃣ Plugin Ecosystem: Install & Share

• One-click Install: Upload a ZIP package to install third-party plugins
• One-click Export: Package custom plugins as ZIP to share with other users
• Modular Isolation: Separate management of built-in tools (tools/) and external plugins (tools_external/)

6️⃣ Group-Based Access Control

Organize modules and proxy servers into groups to control which tools different AI clients can access:

• Group Isolation: Each group has its own set of modules and proxy servers
• Per-Client Access: Clients specify a group via the x-group-id HTTP header — they only see and can call tools in that group
• Default Group: All newly added modules/proxies are automatically added to the default group, ensuring backward compatibility
• Flexible Assignment: A module or proxy server can belong to multiple groups simultaneously

┌──────────────┐         ┌──────────────┐
│  Group A     │         │  Group B     │
│  (Dev Tools) │         │  (Ops Tools) │
│  • t_python  │         │  • t_cli     │
│  • t_notebook│         │  • t_ftp     │
└──────────────┘         └──────────────┘
      ↑ x-group-id: A          ↑ x-group-id: B
 Claude Dev Agent          Claude Ops Agent

7️⃣ Comprehensive Usage Statistics

Intuitively view usage for each tool:

• Call count statistics
• Success rate tracking
• Response time analysis
• 24-hour trend charts

---

🛠️ Built-in Tools

The platform comes with core tool modules ready to use:

Category	Module	Tools	Description
🖥️ CLI Execution	t_cli	run_cli_command, list_directory, get_system_info, get_disk_usage, get_running_processes, find_files...	Execute system commands, view processes, disk monitoring, network info
🐍 Python Execution	t_python	run_python_script, installPackage, run_python_script_async, get_script_status	Safely execute Python scripts, install dependencies, async execution
🤖 GUI Automation	t_autogui	autogui_start_task, autogui_get_status, autogui_get_history, autogui_stop_task	AI-driven desktop automation, automatic mouse and keyboard operations
📓 Notebook	t_notebook	add_note, read_note	Note creation and querying, persistent storage

Featured: AI-Driven GUI Automation

The t_autogui module implements AI-driven desktop automation:

User: Help me open the browser and visit GitHub
Agent: [Calls autogui_start_task] → AI plans task steps → Executes mouse and keyboard operations

This is a killer feature of this platform: AI can operate the computer desktop like a human, completing complex GUI interaction tasks.

---

📦 Extension Tools

Beyond built-in tools, the platform supports installing extension plugins. Currently available extension tool in tools_external/:

Category	Module	Tools	Description
🌐 FTP Transfer	t_ftp	ftp_upload_file, ftp_download_file, ftp_create_directory	FTP file transfer and management

Extension tools are located in the tools_external/ directory and can be loaded on demand through the Web interface or API. You can also develop your own extension tools and install them on the platform.

---

🚀 Quick Start

Requirements

• Python 3.10+
• (Optional) Node.js 18+ - for building the frontend

Installation

# Clone the project
git clone https://github.com/Jayden-Dong/MCPHub.git
cd MCPHub

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

Start the Service

cd app
python main.py

After starting, access:

• 🌐 Web Management Interface: http://localhost:6080
• 📚 API Documentation: http://localhost:6080/docs
• 🔌 MCP Endpoint: http://localhost:6081/mcp

Configure MCP Client

Add the following in Claude Desktop / Cursor/Cherry Studio or other MCP clients:

{
  "mcpServers": {
    "general-tools": {
      "url": "http://localhost:6081/mcp"
    }
  }
}

🎉 Done! Your AI Agent can now use all enabled tools on the platform.

---

📖 Feature Details

Module Management

Manage modules through the Web interface or API:

┌───────────────────────────────────────────────────────────┐
│  Module List              [Scan New Modules] [Install]    
├───────────────────────────────────────────────────────────┤
│  ✅ t_cli        Loaded      [Details] [Reload] [Unload]  
│  ✅ t_python     Loaded      [Details] [Reload] [Unload]  
│  ⏸️ t_autogui    Paused      [Details] [Load]             
│  📦 t_weather    Not Loaded  [Details] [Load]    [Export] 
└───────────────────────────────────────────────────────────┘

Tool-level Control

Enter module details to enable/disable each tool individually:

┌─────────────────────────────────────────────────────────┐
│  t_cli Module Details                                   
├─────────────────────────────────────────────────────────┤
│  🔧 run_cli_command      [✅ Enabled]                   
│  🔧 list_directory       [✅ Enabled]                   
│  🔧 get_system_info      [❌ Disabled]                  
│  🔧 kill_process         [❌ Disabled]  ⚠️ Dangerous      
└─────────────────────────────────────────────────────────┘

Proxy MCP Server

Connect existing MCP Servers to the platform:

Via Web Interface:

1. Navigate to the "Proxy Management" page
2. Click "Add Server"
3. Fill in server name, URL, and transport type
4. Click "Sync Tools" → Tools automatically appear in the platform

Via API:

curl -X POST http://localhost:6080/api/proxy/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem-server",
    "url": "http://localhost:3000/mcp",
    "transport": "streamable-http"
  }'

AI Code Generation

Generate MCP plugins through conversation:

# Start conversation
curl -X POST http://localhost:6080/api/codegen/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Help me create a stock query tool that supports real-time prices and historical trends"}'

# Preview generated code
curl http://localhost:6080/api/codegen/preview/{task_id}

# Install directly to platform
curl -X POST http://localhost:6080/api/codegen/install/{task_id}

Group Management

Groups allow you to organize modules and proxy servers and control which tools each AI client can access.

Via Web Interface:

1. Navigate to the "Group Management" page
2. Click "Create Group" and give it a name
3. Add modules or proxy servers to the group
4. Copy the group ID and pass it to the client via the x-group-id header

Via API:

# Create a group
curl -X POST http://localhost:6080/api/groups \
  -H "Content-Type: application/json" \
  -d '{"name": "dev-tools", "description": "Tools for development"}'

# Add a module to the group
curl -X POST http://localhost:6080/api/groups/{group_id}/modules \
  -H "Content-Type: application/json" \
  -d '{"module_name": "t_python"}'

Configuring the MCP Client with a Group:

{
  "mcpServers": {
    "dev-tools": {
      "url": "http://localhost:6081/mcp",
      "headers": {
        "x-group-id": "<your-group-id>"
      }
    }
  }
}

When a client provides an x-group-id header, it can only list and call tools that belong to that group. Clients without a group header can access all enabled tools.

Usage Statistics

View tool call information:

# Overall overview
curl http://localhost:6080/api/stats/overview

# Statistics by tool
curl http://localhost:6080/api/stats/tools

# Recent call records
curl http://localhost:6080/api/stats/recent?limit=100

Response example:

{
  "total_calls": 1523,
  "success_rate": 0.98,
  "top_tools": [
    {"name": "run_python_script", "calls": 456, "avg_duration_ms": 1234},
    {"name": "run_cli_command", "calls": 312, "avg_duration_ms": 567}
  ]
}

---

🔌 API Documentation

Module Management /api/modules

Method	Path	Description
GET	/api/modules	Get all module list
GET	/api/modules/scan	Scan unloaded modules
POST	/api/modules/load	Load module
POST	/api/modules/{name}/unload	Unload module
POST	/api/modules/{name}/reload	Reload module
POST	/api/modules/tool/enable	Enable tool
POST	/api/modules/tool/disable	Disable tool
POST	/api/modules/install	Install ZIP plugin
GET	/api/modules/{name}/export	Export module as ZIP
DELETE	/api/modules/{name}	Delete external module

Proxy Management /api/proxy

Method	Path	Description
GET	/api/proxy/servers	Get proxy server list
POST	/api/proxy/servers	Add proxy server
PUT	/api/proxy/servers/{id}	Update configuration
DELETE	/api/proxy/servers/{id}	Delete server
POST	/api/proxy/servers/{id}/sync	Sync tool list
POST	/api/proxy/servers/{id}/enable	Enable server
POST	/api/proxy/servers/{id}/disable	Disable server

Group Management /api/groups

Method	Path	Description
GET	/api/groups	Get all groups
POST	/api/groups	Create a group
GET	/api/groups/{group_id}	Get group details
PUT	/api/groups/{group_id}	Update group info
DELETE	/api/groups/{group_id}	Delete group
GET	/api/groups/{group_id}/members	Get all members (modules + proxies)
POST	/api/groups/{group_id}/modules	Add module to group
DELETE	/api/groups/{group_id}/modules/{module_name}	Remove module from group
POST	/api/groups/{group_id}/proxies	Add proxy server to group
DELETE	/api/groups/{group_id}/proxies/{server_id}	Remove proxy from group
GET	/api/groups/by-module/{module_name}	Get groups containing a module
GET	/api/groups/by-proxy/{server_id}	Get groups containing a proxy

Statistics Query /api/stats

Method	Path	Description
GET	/api/stats/overview	Overall statistics overview
GET	/api/stats/modules	Statistics by module
GET	/api/stats/tools	Statistics by tool
GET	/api/stats/recent	Recent call records

AI Code Generation /api/codegen

Method	Path	Description
POST	/api/codegen/chat	Conversational code generation
POST	/api/codegen/chat/stream	Streaming conversation
GET	/api/codegen/preview/{task_id}	Preview generated code
POST	/api/codegen/install/{task_id}	Install to platform
POST	/api/codegen/download/{task_id}	Download ZIP

---

🧩 Development Guide

Creating Custom Modules

For detailed module development specifications, please refer to MCP_MODULE_DEV_GUIDE.md.

Quick Start:

my_module/
├── __init__.py          # Package marker
├── MODULE_INFO          # Module metadata
├── my_module_mcp.py     # MCP tool registration
├── my_module_tool.py    # Business logic
└── requirements.txt     # Optional dependencies

MODULE_INFO:

{
  "display_name": "My Tool",
  "version": "1.0.0",
  "description": "Tool description",
  "author": "Your Name"
}

my_module_mcp.py:

from mcp_service import mcp
from config_py.config import settings
from config_py.prompt import prompt_manager
from utils import com_utils
from utils.com_utils import get_mcp_exposed_url

TOOL_NAME = "my_tool"

@mcp.tool(
    name=f'{settings.MCP_TOOL_NAME_PREFIX}{TOOL_NAME}',
    description=f'MCP Server URL: {get_mcp_exposed_url()}. {prompt_manager.get(TOOL_NAME)}',
    enabled=com_utils.get_tool_enable(TOOL_NAME),
)
def my_tool(param: str) -> dict:
    """Tool description"""
    return {"success": True, "data": "result"}

Package & Share

# Package
zip -r my_module.zip my_module/

# Install
curl -X POST http://localhost:6080/api/modules/install \
  -F "file=@my_module.zip"

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    MCP Client (Claude / Cursor)                 │
└───────────────────────────────┬─────────────────────────────────┘
                                │ MCP Protocol (HTTP Streamable)
                                ▼ :6081
┌─────────────────────────────────────────────────────────────────┐
│                    MCP Service (FastMCP)                        
│  ┌───────────────────────────────────────────────────────────┐ 
│  │  Middleware Layer                                          
│  │  • RequestMCPMiddleware (logging/statistics)               
│  │  • ToolDescriptionCheckerMiddleware (description hot update)
│  │  • ToolEnabledCheckerMiddleware (tool filtering)          
│  └───────────────────────────────────────────────────────────┘  
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              
│  │  Built-in   │  │  External   │  │  Proxy      │              
│  │  Tools      │  │  Plugins    │  │  Tools      │              
│  │  tools/     │  │  external/  │  │  proxy/     │              
│  └─────────────┘  └─────────────┘  └─────────────┘              
└─────────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                    REST API (FastAPI) :6080                     │
│  /api/modules  /api/stats  /api/proxy  /api/codegen  /api/auth  │
└───────────────────────────────┬─────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                    Web Frontend (Vue 3)                         │
│  Module Management | Tool Control | Proxy Config | Statistics   │
└─────────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                    Data Layer (SQLite)                          │
│  Module Status | Tool Config | Call Statistics | Proxy Config   │
│  User Authentication                                            │
└─────────────────────────────────────────────────────────────────┘

---

📁 Project Structure

MCPHub/
├── requirements.txt              # Python dependencies
├── README.md                     # This file
├── MCP_MODULE_DEV_GUIDE.md       # Module development guide
├── config/
│   ├── config.json               # Main configuration file
│   └── mcp_hub.db               # SQLite database
└── app/
    ├── main.py                   # FastAPI entry point
    ├── mcp_service.py            # MCP service initialization
    ├── my_mcp_middleware.py      # MCP middleware
    ├── config_py/                # Configuration management
    ├── managers/                 # Core managers
    │   ├── module_manager.py     # Module lifecycle
    │   ├── proxy_manager.py      # Proxy servers
    │   └── stats_manager.py      # Statistics management
    ├── api/                      # REST API
    ├── tools/                    # Built-in modules
    │   ├── t_autogui/            # GUI automation
    │   ├── t_cli/                # CLI commands
    │   ├── t_python/             # Python execution
    │   └── ...
    ├── tools_external/           # External plugins
    ├── toolsmcp/                 # MCP tool wrappers
    └── web/                      # Vue 3 frontend

---

⚙️ Configuration

Main configuration file: config/config.json

{
  "api": {
    "title": "MCPHub Service",
    "version": "1.0.0"
  },
  "server": {
    "host": "0.0.0.0",
    "port": 6080
  },
  "mcp": {
    "service_name": "mcphub",
    "host": "0.0.0.0",
    "port": 6081,
    "path": "/mcp",
    "tool_name_prefix": "",
    "module_enable": [
      {
        "enable": true,
        "module_name": "tools.t_cli.cli_mcp",
        "disable_tool": [],
        "config": {}
      }
    ]
  },
  "database": {
    "db_path": "./config/mcp_hub.db"
  },
  "auth": {
    "secret_key": "your-secret-key",
    "token_expire_hours": 24
  }
}

Configuration	Description
mcp.tool_name_prefix	Tool name prefix for distinguishing multi-instance deployments
mcp.module_enable	List of modules to auto-load on startup
module_enable[].disable_tool	List of disabled tool names in the module
module_enable[].config	Custom configuration passed to the module

---

🤝 Contributing

Contributions, bug reports, and suggestions are welcome!

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

---

📄 License

This project is licensed under the MIT License.

---

🙏 Acknowledgments

• FastMCP - Framework for quickly building MCP Servers
• MCP Protocol - Model Context Protocol specification
• FastAPI - Modern high-performance Python web framework

---

Empower AI Agents with Infinite Possibilities 🚀