MCP Unified Hub

A MindsDB-powered, all-in-one Model Context Protocol (MCP) server hub that provides unified access to 25+ services through a single endpoint. Connect once, access everything from any IDE or platform.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     MCP Unified Gateway                      │
│                    http://localhost:3100                     │
│                                                               │
│  Single endpoint for all MCP capabilities                    │
│  • Notion • MongoDB • PostgreSQL • Neon • Redis              │
│  • Stripe • Playwright • Apify • AWS • Kubernetes            │
│  • Discord • Google Maps • Hugging Face • LinkedIn           │
│  • Reddit • Obsidian • Postman • Heroku • Docker             │
│  • Filesystem • Memory • LLM Text • Markdownify              │
│  • Handwriting OCR • Sequential Thinking • And more...       │
└───────────────────┬─────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
┌───────▼────────┐    ┌────────▼────────┐
│   MindsDB      │    │   Databases     │
│  (AI/ML Core)  │    │  • PostgreSQL   │
│  Port: 47334   │    │  • MongoDB      │
└────────────────┘    │  • Redis        │
                      └─────────────────┘

Features

• Single Unified Endpoint: One gateway (http://localhost:3100) for all MCP services
• MindsDB Integration: Leverage MindsDB's AI/ML capabilities across all data sources
• 25+ Service Integrations: Access databases, APIs, AI models, and tools
• Multi-IDE Support: Connect from Claude Code, VSCode, Cursor, or any MCP-compatible platform
• Docker-Based: Fully containerized, portable, and easy to deploy
• HTTP Transport: Simple HTTP-based MCP protocol (no stdio complexity)
• Monitoring: Built-in Prometheus metrics for observability

Quick Start

Prerequisites

• Docker Desktop installed and running
• At least 4GB RAM allocated to Docker
• API keys for services you want to use (optional, configured per service)

Installation

1. Clone or navigate to the MCP Hub directory:

   cd C:\Users\momo-\mcp-hub

2. Configure environment variables:

   # Windows
   copy .env.template .env
   notepad .env
   
   # Linux/Mac
   cp .env.template .env
   nano .env

3. Start the MCP Hub:

   # Windows
   start.bat
   
   # Linux/Mac
   chmod +x start.sh
   ./start.sh

4. Verify it's running:

   # Check health
   curl http://localhost:3100/health
   
   # List available tools
   curl http://localhost:3100/tools

Connecting to IDEs

Claude Code

Add to your Claude Code configuration:

claude mcp add --transport http mcp-hub http://localhost:3100/mcp

Or manually add to .mcp.json:

{
  "mcpServers": {
    "mcp-unified-hub": {
      "transport": "http",
      "url": "http://localhost:3100/mcp",
      "description": "Unified access to all MCP services"
    }
  }
}

VSCode / Cursor / Windsurf

Add to your settings.json:

{
  "mcp.servers": {
    "unified-hub": {
      "type": "http",
      "url": "http://localhost:3100/mcp"
    }
  }
}

Cline Extension

Configuration in Cline settings:

{
  "mcpServers": {
    "mcp-hub": {
      "command": "node",
      "args": ["-e", "require('http').get('http://localhost:3100/mcp')"],
      "env": {}
    }
  }
}

Remote Connection (From Any Machine)

Replace localhost with your server's IP address:

claude mcp add --transport http mcp-hub http://YOUR_SERVER_IP:3100/mcp

Available Services

Databases & Storage

• PostgreSQL - Relational database operations
• MongoDB - Document database operations
• Neon - Serverless Postgres
• Redis - Cache and pub/sub operations

AI & ML

• MindsDB - AI/ML queries and predictions
• Hugging Face - Access to HF models
• LLM Text - Text processing with various LLMs

Productivity & Content

• Notion - Workspace management
• Obsidian - Note-taking and PKM
• Discord - Bot operations and messaging
• LinkedIn - Professional networking
• Reddit - Social media integration

Developer Tools

• GitHub - Repository management
• Postman - API testing and collections
• Docker - Container management
• Kubernetes - Cluster operations

Cloud & Infrastructure

• AWS - S3, Lambda, DynamoDB, and more
• Heroku - App deployment and management

Automation & Testing

• Playwright - Browser automation
• Apify - Web scraping
• ExecuteAutomation Playwright - Advanced browser testing

APIs & Services

• Stripe - Payment processing
• Google Maps - Maps and geolocation
• Handwriting OCR - Text extraction from images

Utilities

• Filesystem - File operations
• Memory - Persistent context storage
• Markdownify - HTML to Markdown conversion
• Sequential Thinking - Reasoning and logic chains

Usage Examples

Execute a Tool via HTTP

curl -X POST http://localhost:3100/execute \
  -H "Content-Type: application/json" \
  -d '{
    "handler": "notion",
    "tool": "search",
    "params": {
      "query": "project notes"
    }
  }'

JSON-RPC 2.0 (Standard MCP Protocol)

curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notion.search",
    "params": {
      "query": "project notes"
    },
    "id": 1
  }'

MindsDB Query

curl -X POST http://localhost:3100/mindsdb/api/sql/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM my_model WHERE input='\''analyze this'\''"
  }'

Management Commands

# Start the hub
start.bat        # Windows
./start.sh       # Linux/Mac

# Stop the hub
stop.bat         # Windows
./stop.sh        # Linux/Mac

# Check status
status.bat       # Windows
docker-compose ps # Linux/Mac

# View logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f mcp-gateway
docker-compose logs -f mindsdb-core

# Restart services
docker-compose restart

# Rebuild after code changes
docker-compose up -d --build

Service Endpoints

Service	Port	URL
MCP Gateway	3100	http://localhost:3100
MindsDB HTTP	47334	http://localhost:47334
MindsDB MySQL	47335	localhost:47335
PostgreSQL	5432	localhost:5432
MongoDB	27017	localhost:27017
Redis	6379	localhost:6379
Prometheus	9090	http://localhost:9090

Extending the Hub

Adding a New Handler

1. Create a new handler file:

   cd gateway/handlers
   # Copy the template
   cp base.js mynewservice.js

2. Implement your handler (see handlers/README.md for template)

3. Register in gateway/server.js:

   const MyNewServiceHandler = require('./handlers/mynewservice');
   // ...
   handlers.set('mynewservice', new MyNewServiceHandler());

4. Add required environment variables to .env.template

5. Rebuild:

   docker-compose up -d --build

Troubleshooting

Gateway won't start

# Check if port 3100 is already in use
netstat -ano | findstr :3100    # Windows
lsof -i :3100                   # Linux/Mac

# Check Docker logs
docker-compose logs mcp-gateway

Handler not working

# Verify environment variables
docker-compose exec mcp-gateway env | grep API_KEY

# Check handler initialization
docker-compose logs mcp-gateway | grep "initialized"

MindsDB connection issues

# Test MindsDB directly
curl http://localhost:47334/api/status

# Check MindsDB logs
docker-compose logs mindsdb-core

Security Notes

• Never commit .env file - It contains API keys
• Use strong passwords for database services
• Restrict port access in production environments
• Use HTTPS when exposing to the internet
• Rotate API keys regularly

Performance Optimization

• Allocate at least 4GB RAM to Docker
• Use Redis for caching frequently accessed data
• Monitor with Prometheus at http://localhost:9090
• Scale individual services as needed:

  docker-compose up -d --scale mcp-gateway=3

Backup & Restore

# Backup data volumes
docker-compose down
docker run --rm -v mcp-postgres-data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-backup.tar.gz /data

# Restore
docker run --rm -v mcp-postgres-data:/data -v $(pwd):/backup alpine tar xzf /backup/postgres-backup.tar.gz

Contributing

To add a new service integration:

1. Create handler in gateway/handlers/
2. Add configuration to .env.template
3. Update docker-compose.yml if new containers needed
4. Update this README
5. Test thoroughly
6. Submit PR

License

MIT License - See LICENSE file for details

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• Built with MindsDB
• Model Context Protocol by Anthropic
• Community MCP server implementations

---

MCP Unified Hub - Your one-stop solution for MCP integrations