MCP Manager

MCP Manager is an open-source tool that provides a single control point to organize, activate, and dynamically manage groups of Model Context Protocol (MCP) services so users can quickly switch between clean, purpose-built environments for their different workflows.

Features

• 🔧 Manage MCP Definitions - Store and manage multiple MCP server configurations
• 📦 Workspace Management - Group MCPs into workspaces for different workflows
• 🚀 Workspace Aggregator - Serve multiple MCPs as a single aggregated endpoint
• 🎯 Easy Integration - Works seamlessly with Cursor, Claude, and other MCP clients
• 🔄 Dynamic Routing - Automatically routes requests to the appropriate MCP server

Installation

Using npm (recommended)

npm install -g @flemzord/mcp-manager

Using npx (no installation required)

npx @flemzord/mcp-manager --help

From source

git clone https://github.com/flemzord/mcp-manager.git
cd mcp-manager
npm install
npm run build
npm link  # Makes 'mcp-manager' available globally

Quick Start

1. Add MCP Definitions

First, define the MCP servers you want to use:

# Add a memory server for temporary storage
mcp-manager mcp add memory \
  --command "npx" \
  --arg "@modelcontextprotocol/server-memory"

# Add a filesystem server with access to your projects
mcp-manager mcp add filesystem \
  --command "npx" \
  --arg "@modelcontextprotocol/server-filesystem" \
  --arg "/path/to/projects"

# Add a GitHub server (requires GITHUB_TOKEN environment variable)
mcp-manager mcp add github \
  --command "npx" \
  --arg "@modelcontextprotocol/server-github" \
  --env "GITHUB_TOKEN=$GITHUB_TOKEN"

2. Create Workspaces

Group MCPs into workspaces for different use cases:

# Development workspace
mcp-manager workspace add dev \
  --description "Development environment" \
  --member memory \
  --member filesystem \
  --member github

# Data analysis workspace
mcp-manager workspace add data \
  --description "Data analysis tools" \
  --member postgres \
  --member elasticsearch

3. Serve a Workspace

Serve a workspace as a single aggregated MCP endpoint:

# Serve the dev workspace
mcp-manager workspace serve dev

# Test with dry run first
mcp-manager workspace serve dev --dry-run

4. Configure in Cursor

Add to your Cursor MCP configuration (.cursorrules or settings):

{
  "mcpServers": {
    "dev-workspace": {
      "command": "mcp-manager",
      "args": ["workspace", "serve", "dev"]
    }
  }
}

Or using npx:

{
  "mcpServers": {
    "dev-workspace": {
      "command": "npx",
      "args": ["mcp-manager", "workspace", "serve", "dev"]
    }
  }
}

Usage Examples

Managing MCPs

# List all stored MCP definitions
mcp-manager mcp list

# Show details of a specific MCP
mcp-manager mcp show memory

# Update an MCP definition
mcp-manager mcp add memory \
  --command "npx" \
  --arg "@modelcontextprotocol/server-memory" \
  --arg "--enhanced"  # Updates the existing definition

# Remove an MCP definition
mcp-manager mcp remove memory

# Test run an MCP directly
mcp-manager mcp run memory

Managing Workspaces

# List all workspaces
mcp-manager workspace list

# Show workspace details
mcp-manager workspace show dev

# Interactively manage workspace members
mcp-manager workspace manage dev

# List members of a workspace
mcp-manager workspace members dev

# Run all MCPs in a workspace sequentially (for testing)
mcp-manager workspace run dev

# Remove a workspace
mcp-manager workspace remove dev

Advanced Workspace Serving

# Serve with additional environment variables
mcp-manager workspace serve dev \
  --env API_KEY=xxx \
  --env DEBUG=true

# Serve with custom working directory
mcp-manager workspace serve dev --cwd /path/to/project

# See what would be served without starting
mcp-manager workspace serve dev --dry-run

Workspace Aggregator

The workspace aggregator allows you to combine multiple MCP servers into a single endpoint. This is particularly useful for:

• Simplified Configuration - Configure once in your editor instead of multiple times
• Unified Interface - Access all tools through a single connection
• Resource Sharing - MCPs in the same workspace can complement each other
• Easy Switching - Switch between different workspace configurations quickly

How It Works

1. Tool Prefixing: Tools from each MCP are prefixed with the MCP ID

   • memory server's store tool becomes memory.store
   • github server's search_issues tool becomes github.search_issues

2. Automatic Routing: The aggregator automatically routes requests to the correct MCP

3. Combined Manifests: All tools, prompts, and resources are merged into a single manifest

Example: Development Workspace

# Setup a comprehensive development workspace
mcp-manager mcp add memory --command "npx" --arg "@modelcontextprotocol/server-memory"
mcp-manager mcp add github --command "npx" --arg "@modelcontextprotocol/server-github"
mcp-manager mcp add filesystem --command "npx" --arg "@modelcontextprotocol/server-filesystem" --arg "."
mcp-manager mcp add postgres --command "npx" --arg "@modelcontextprotocol/server-postgres"

# Create and serve the workspace
mcp-manager workspace add fullstack \
  --member memory \
  --member github \
  --member filesystem \
  --member postgres

mcp-manager workspace serve fullstack

Now in Cursor, you have access to all tools through a single connection:

• memory.create_entities - Store information in memory
• github.search_issues - Search GitHub issues
• filesystem.read_file - Read local files
• postgres.query - Execute database queries

Environment Variables

MCP Manager supports environment variables at multiple levels:

# MCP-level environment variables
mcp-manager mcp add github --env "GITHUB_TOKEN=$GITHUB_TOKEN"

# Workspace-level environment variables (shared by all MCPs)
mcp-manager workspace add dev --env "LOG_LEVEL=debug"

# Runtime environment variables (override for this session)
mcp-manager workspace serve dev --env "API_KEY=xxx"

Priority order (later overrides earlier):

1. MCP-level environment variables
2. Workspace-level environment variables
3. Runtime environment variables

Configuration Storage

MCP Manager stores its configuration in platform-specific locations:

• macOS: ~/Library/Application Support/mcp-manager/config.yaml
• Linux: ~/.config/mcp-manager/config.yaml
• Windows: %APPDATA%\mcp-manager\config.yaml

You can manually edit this file if needed, but using the CLI commands is recommended.

Troubleshooting

MCP Not Starting

If an MCP fails to start:

• Check error messages in stderr
• Verify the command works standalone: mcp-manager mcp run <id>
• Ensure required environment variables are set
• Check that the MCP package is installed

Tools Not Appearing

If tools aren't showing up:

• Verify the MCP supports the tools capability
• Check that the MCP started successfully
• Use --dry-run to inspect the manifest
• Look for errors in the aggregator logs

Connection Issues

If Cursor/Claude can't connect:

• Ensure mcp-manager is in your PATH
• Try using the full path to mcp-manager
• Check that the workspace exists: mcp-manager workspace list
• Test the workspace directly: mcp-manager workspace serve <id>

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT