# mcp-manager2

**Repository Path**: wshmaple/mcp-manager2

## Basic Information

- **Project Name**: mcp-manager2
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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)

```bash
npm install -g @flemzord/mcp-manager
```

### Using npx (no installation required)

```bash
npx @flemzord/mcp-manager --help
```

### From source

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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):

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

Or using npx:

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

## Usage Examples

### Managing MCPs

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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