mcp-uni

mcp-uni

A universal MCP server that acts as a unified gateway for dynamically connecting and managing multiple MCP servers via a single HTTP endpoint.

Category
访问服务器

README

English | 中文

MCP-UNI

MCP-UNI is a Model Context Protocol (MCP) universal server that acts as a unified gateway for connecting and managing multiple MCP servers. It provides a single HTTP endpoint to dynamically connect, disconnect, and interact with various MCP servers without requiring static configuration.

Features

  • 🔌 Dynamic MCP Server Management: Connect and disconnect MCP servers at runtime
  • 🌐 HTTP Server Interface: RESTful API with Server-Sent Events (SSE) support
  • 🔗 Multiple Transport Support: Supports both SSE and stdio transports
  • 🛠️ Tool Aggregation: Exposes all connected MCP server tools through a unified interface
  • 📚 Resource Management: Access resources and resource templates from connected servers
  • 💬 Prompt Management: Manage prompts across multiple MCP servers
  • 🔄 Auto-retry: Built-in retry mechanism for connection failures
  • 📋 Real-time Updates: Dynamic tool list updates when servers connect/disconnect

Architecture

MCP-UNI acts as a proxy/gateway between clients and multiple MCP servers:

Client ──HTTP/SSE──> MCP-UNI ──stdio/SSE──> MCP Server 1
                        │
                        ├─────stdio/SSE──> MCP Server 2
                        │
                        └─────stdio/SSE──> MCP Server N

Installation

Using npx (Recommended)

npx mcp-uni

From npm (Coming Soon)

npm install -g mcp-uni

From Source

git clone https://github.com/yourusername/mcp-uni.git
cd mcp-uni
npm install
npm run build

Quick Start

Method 1: Using Configuration File (Recommended)

  1. Create a configuration file (mcp-uni.config.json):

    {
  "mcpServers": {
    "everything": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {}
    }
  }
}

  2. Start the MCP-UNI server:

    # Using npx (no installation required)
npx mcp-uni

# With custom port
npx mcp-uni --port 8000

# With custom config file
npx mcp-uni --config /path/to/your-config.json

# Or if installed globally
mcp-uni
mcp-uni --port 8000

    The server will start on http://localhost:7200 (or your specified port) with SSE endpoint at /stream, and automatically connect the MCP servers defined in your configuration file.

Method 2: Manual Connection

  1. Start the MCP-UNI server:

    # Using npx (no installation required)
npx mcp-uni

# With custom port
npx mcp-uni --port 8000

# Or if installed globally
mcp-uni
mcp-uni --port 8000

    The server will start on http://localhost:7200 (or your specified port) with SSE endpoint at /stream.

  2. Connect an MCP server:

    curl -X POST http://localhost:7200/tools/connect_mcp \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-mcp-server",
    "transportConfig": {
      "type": "stdio",
      "command": "node",
      "args": ["./my-mcp-server/index.js"],
      "env": {},
      "cwd": "/path/to/server"
    }
  }'

  3. List connected servers:

    curl -X POST http://localhost:7200/tools/list_mcp \
  -H "Content-Type: application/json" \
  -d '{}'

Configuration

Configuration File

MCP-UNI supports a configuration file (mcp-uni.config.json) to automatically connect MCP servers on startup. This allows you to pre-configure your MCP servers without manually connecting them each time.

Configuration File Format

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {}
    }
  }
}

Configuration File Location

  • Default: mcp-uni.config.json in the current working directory
  • Custom: Use --config option to specify a different path

Example Configuration Files

Multiple MCP Servers:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    },
    "everything": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {}
    },
    "database": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "database_mcp_server"],
      "env": {
        "DB_URL": "sqlite:///app.db"
      },
      "cwd": "/path/to/db/server"
    }
  }
}

SSE Transport Configuration:

{
  "mcpServers": {
    "remote-server": {
      "type": "sse",
      "url": "http://example.com/sse",
      "query": {
        "param1": "value1"
      },
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

Transport Configuration

MCP-UNI supports two types of transport configurations:

SSE Transport

{
  "type": "sse",
  "url": "http://example.com/sse",
  "query": {
    "param1": "value1"
  },
  "headers": {
    "Authorization": "Bearer token"
  }
}

Stdio Transport

{
  "type": "stdio",
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "ENV_VAR": "value"
  },
  "cwd": "/path/to/working/directory"
}

Command Line Options

mcp-uni [options]

Options:
  -p, --port <number>    Port to listen on (default: 7200)
  -s, --stream <path>    Stream endpoint path (default: /stream)
  -c, --config <path>    Config file path (default: mcp-uni.config.json)
  -h, --help            Display help for command
  -V, --version         Display version number

Examples

# Start server on default port (7200) with default config
npx mcp-uni

# Start server on custom port
npx mcp-uni --port 8000

# Start server with custom config file
npx mcp-uni --config /path/to/my-config.json

# Start server with custom port and config
npx mcp-uni --port 8000 --config ./configs/production.json

# Start server with custom stream endpoint
npx mcp-uni --port 8000 --stream /events

# Show help
npx mcp-uni --help

# Show version
npx mcp-uni --version

API Reference

Built-in Tools

MCP-UNI provides these management tools:

connect_mcp

Connect a new MCP server to the host.

Parameters:

  • name (string): Unique name for the MCP server
  • transportConfig (object): Transport configuration (see above)

disconnect_mcp

Disconnect an MCP server from the host.

Parameters:

  • name (string): Name of the MCP server to disconnect

list_mcp

List all currently connected MCP servers.

Parameters: None

Dynamic Tools

All tools from connected MCP servers are automatically exposed through MCP-UNI with their original names and schemas.

HTTP Endpoints

  • POST /tools/{tool_name} - Execute a tool
  • GET /stream - SSE endpoint for real-time updates
  • GET /health - Health check endpoint

Usage Examples

Connecting Multiple Servers

# Connect a file system MCP server
curl -X POST http://localhost:7200/tools/connect_mcp \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem",
    "transportConfig": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {},
      "cwd": "."
    }
  }'

# Connect a database MCP server
curl -X POST http://localhost:7200/tools/connect_mcp \
  -H "Content-Type: application/json" \
  -d '{
    "name": "database",
    "transportConfig": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "database_mcp_server"],
      "env": {"DB_URL": "sqlite:///app.db"},
      "cwd": "/path/to/db/server"
    }
  }'

Using Connected Server Tools

Once servers are connected, their tools become available:

# Use filesystem server tool
curl -X POST http://localhost:7200/tools/read_file \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp/example.txt"}'

# Use database server tool
curl -X POST http://localhost:7200/tools/execute_query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM users LIMIT 10"}'

Development

Project Structure

src/
├── index.ts              # Entry point and HTTP server setup
├── server.ts             # MCP server implementation
├── host.ts               # MCP host for managing connections
└── utils/
    ├── schema-converter.ts # JSON Schema to Zod conversion utilities
    └── utils.ts           # Utility functions

Building

npm run build

The compiled JavaScript will be output to the build/ directory.

Key Components

  • McpHost (host.ts:37): Manages connections to multiple MCP servers
  • createServer (server.ts:15): Creates the unified MCP server instance
  • Schema Conversion (utils/schema-converter.ts): Converts JSON schemas to Zod schemas
  • Transport Management (host.ts:166): Handles different transport types (SSE/stdio)

Error Handling

MCP-UNI includes robust error handling:

  • Connection Retries: Automatic retry with backoff for failed connections (3 retries, 2.5s delay)
  • Tool Execution: Proper error propagation from connected servers
  • Graceful Cleanup: Automatic cleanup of connections on server shutdown

Requirements

  • Node.js 16+ (ES modules required)
  • TypeScript 5+

Dependencies

  • @modelcontextprotocol/sdk: MCP SDK for client/server implementation
  • mcp-proxy: HTTP proxy server for MCP protocol
  • zod: Schema validation and type safety

License

MIT

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Support

For issues and questions:

  • Create an issue on GitHub
  • Check existing documentation
  • Review the MCP specification

MCP-UNI simplifies MCP server management by providing a unified, dynamic gateway for all your Model Context Protocol servers.

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选