nazar256/combine-mcp

An MCP (Model Context Protocol) aggregator that allows you to combine multiple MCP servers into a single interface. The code is mostly AI-generated.
Why combine MCP servers into one?
The primary reason for this app was to work around Cursor's limitation of only being able to use 2 MCP servers at a time. No matter which, in my case when I added 3rd MCP server, it was breaking the ability to use one of other two.
Overview
The MCP Aggregator acts as a bridge between Cursor (or any other MCP client) and multiple MCP servers. It functions both as an MCP server (when talking to Cursor) and as an MCP client (when talking to backend MCP servers).
Key features:
- Provides a stdio interface for Cursor and other MCP clients
- Connects to multiple backend MCP servers
- Prefixes methods from backend servers (e.g., "shortcut_search_stories" for "search_stories" method from a "shortcut" MCP)
- Automatically sanitizes tool names by replacing dashes with underscores for Cursor compatibility
- Configurable via environment variables and JSON config file
- Debug logging with configurable levels
Installation
Using install script (recommended)
You can install the latest version of combine-mcp using our installation script:
The script will:
- Detect your operating system and architecture
- Download the appropriate pre-compiled binary
- Verify the checksum
- Install it to a suitable location in your PATH
- Make it executable
Using go install (alternative)
Using Docker (alternative)
You can run combine-mcp directly using Docker without installing it locally:
To use it with Cursor, you'd need to configure the MCP server to use Docker:
Using the Makefile
The project includes a Makefile for common tasks:
Usage
Configure the aggregator
Basically you can copy existing Cursor MCP config to a location of your choice, let's say ~/.config/mcp/config.json. It should look like this:
Nice feature for Cursor users is filtering tools from MCP servers. You can manage tools to not reach the limit of 40 tools in Cursor and not expose the ones you don't want Cursor to use.
Configure the aggregator in Cursor
Now in Cursor config you may leave the only one MCP server - aggregator. The config may look like this (assuming you have combine-mcp binary is instlaled your PATH and you have ~/.config/mcp/config.json file):
Environment Variables
- MCP_CONFIG: Path to the configuration file (required)
- MCP_LOG_LEVEL: Logging level (error, info, debug, trace) - default: info
- MCP_LOG_FILE: Path to the log file
- MCP_PROTOCOL_VERSION: Force a specific protocol version for compatibility
- MCP_CURSOR_MODE: Enable Cursor-specific compatibility adjustments
Use cases
Unified MCP config for multiple clients
One practical use case is to maintain a **single MCP configuration file** that is shared across different MCP-capable clients (e.g. Cursor, Windsurf, Gemini-CLI, Codex, Claude Code, GitHub Copilot agents, etc.).
Instead of configuring each client with its own list of MCP servers and duplicating secrets, you: