Key Features • Quick Start • Feature Details • API Documentation • Development Guide
Default credentials: username
admin, passwordadmin123
Manage all MCP modules with support for loading, unloading, and reloading operations
Enable/disable each tool individually, edit tool descriptions in real-time
Proxy existing MCP Servers without modification
Visualize tool call counts, success rates, and response times
Generate MCP plugin code through natural language conversation
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
└─────────────────────────────────────────────────────────────────────┘
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.
- 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
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.
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!
- 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/)
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-idHTTP 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
Intuitively view usage for each tool:
- Call count statistics
- Success rate tracking
- Response time analysis
- 24-hour trend charts
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 |
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.
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.
- Python 3.10+
- (Optional) Node.js 18+ - for building the frontend
# 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.txtcd app
python main.pyAfter starting, access:
- 🌐 Web Management Interface:
http://localhost:6080 - 📚 API Documentation:
http://localhost:6080/docs - 🔌 MCP Endpoint:
http://localhost:6081/mcp
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.
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]
└───────────────────────────────────────────────────────────┘
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
└─────────────────────────────────────────────────────────┘
Connect existing MCP Servers to the platform:
Via Web Interface:
- Navigate to the "Proxy Management" page
- Click "Add Server"
- Fill in server name, URL, and transport type
- 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"
}'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}Groups allow you to organize modules and proxy servers and control which tools each AI client can access.
Via Web Interface:
- Navigate to the "Group Management" page
- Click "Create Group" and give it a name
- Add modules or proxy servers to the group
- Copy the group ID and pass it to the client via the
x-group-idheader
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.
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=100Response 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}
]
}| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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
zip -r my_module.zip my_module/
# Install
curl -X POST http://localhost:6080/api/modules/install \
-F "file=@my_module.zip"┌─────────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────────┘
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
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 |
Contributions, bug reports, and suggestions are welcome!
- Fork this repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Create a Pull Request
This project is licensed under the MIT License.
- 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 🚀
