mcp-manager-cli 0.0.2

A unified CLI and daemon/service to manage and proxy multiple MCP servers, with robust logging and a modern CLI UX.

MCP Manager CLI

A unified CLI and daemon/service to manage and proxy multiple MCP servers, with robust logging and a modern CLI UX.

Table of Contents

• Features
• Architecture Overview
• Installation
• Configuration
• Security & API Key Authentication
• Quickstart
• CLI User Interface Example
• Available CLI Commands
• Roadmap
• License

Features

• Daemon/Service Architecture: Background FastAPI HTTP server for robust, multi-process management.
• Unified CLI: Interactive CLI for all management and tool operations.
• Server Management: Start, stop, and monitor multiple MCP servers defined in a config file.
• SSE Support: Built-in /sse, /messages/, and /mcp-server-name/sse endpoints for real-time communication with individual servers.
• All runtime and config files are stored in the .cache/ directory for easy management and cleanup.

Architecture Overview

flowchart TD
    classDef user fill:#e0f7fa,stroke:#00796b,stroke-width:2px;
    classDef daemon fill:#fff3e0,stroke:#f57c00,stroke-width:2px;
    classDef process fill:#e8f5e9,stroke:#388e3c,stroke-width:2px;

    subgraph User
        CLI["👤 CLI (mcp-manager)"]:::user
        OtherClient["👤 Other MCP Client (SSE/WebSocket)"]:::user
    end

    subgraph "MCP Manager Daemon (FastAPI)"
        APIServer["🖥️ API Server (FastAPI)"]:::daemon
        ServerManager["🗄️ ServerManager"]:::daemon
        Config["📝 Config (.cache/mcp_config.json)"]:::daemon
    end

    subgraph "Managed MCP Servers"
        MCPServer1["⚙️ MCP Server 1 (Stdio Process)"]:::process
        MCPServer2["⚙️ MCP Server 2 (Stdio Process)"]:::process
        MCPServerN["..."]:::process
    end

    CLI -- "HTTP" --> APIServer
    OtherClient -- "SSE" --> APIServer
    APIServer -- "Reads/writes" --> Config
    APIServer -- "Manages via" --> ServerManager
    ServerManager -- "Spawns & manages via stdio/stdout" --> MCPServer1
    ServerManager -- "Spawns & manages via stdio/stdout" --> MCPServer2
    ServerManager -- "Spawns & manages via stdio/stdout" --> MCPServerN

Installation

Quick install from PyPI:

pip install mcp-manager-cli

Or, to install from source:

1. Clone the repo:

   git clone <repo-url>
   cd mcp-manager
   

2. Install uv (recommended for Python environments).
3. Create and activate a virtual environment:

   uv venv .venv
   source .venv/bin/activate
   

4. Install dependencies:

   uv pip install -e .
   

Configuration

Define MCP servers in .cache/mcp_config.json:

{
  "mcpServers": {
    "hackernews": {
      "command": "uvx",
      "args": [
        "mcp-hn"
      ],
      "auto_start": true
    }
  }
}

• auto_start: If true, the server starts automatically with the daemon.
• After editing .cache/mcp_config.json, run server reload in the CLI to apply changes.
• All config and runtime files are stored in the .cache/ directory.

Security & API Key Authentication

• On first run, the server generates an API key in .cache/mcp_manager_api_key.txt.
• All management endpoints require this API key as a Bearer token in the Authorization header.
• The CLI uses this API key automatically.
• To view the API key:

  api-key
  

• To regenerate the API key:

  regenerate-api-key
  

• For manual requests (e.g., curl/Postman), use:

  Authorization: Bearer <your-api-key>
  

• API key file location: .cache/mcp_manager_api_key.txt

Quickstart

1. Start the CLI:

   mcp-manager
   

2. Example commands:
   • daemon start (default port 4123)
   • daemon start --port 5000 (custom port)
   • server list, server reload, tools list, api-key, regenerate-api-key, etc.
3. Type help for all commands.
4. All config and runtime files are in .cache/.

SSE Endpoints

The MCP Manager daemon provides several SSE (Server-Sent Events) endpoints for real-time communication:

• Unified SSE Proxy:
  • GET /sse — Connect to all managed servers via a unified SSE stream.
• Per-Server SSE Endpoint:
  • GET /<mcp-server-name>/sse — Connect directly to a specific managed server's SSE stream. Replace <mcp-server-name> with the name of your server (e.g., /hackernews/sse).
• Messages Endpoint:
  • POST /messages — Send messages to all servers (with authentication).
  • POST /<mcp-server-name>/messages — Send messages to a specific server.

Tip: Use the per-server SSE endpoint (/<mcp-server-name>/sse) for direct, real-time communication with a single managed server.

CLI User Interface Example

  __  __  ___ ___   __  __                             
 |  \/  |/ __| _ \ |  \/  |__ _ _ _  __ _ __ _ ___ _ _ 
 | |\/| | (__|  _/ | |\/| / _` | ' \/ _` / _` / -_) '_|
 |_|  |_|\___|_|   |_|  |_|\__,_|_||_\__,_\__, \___|_|  
                                         |___/          ☁️ CloudThinker

MCP Manager: Multi MCP Server Control Panel. Powered by CloudThinker (https://www.cloudthinker.io)
Type 'help' for commands, 'exit' to quit.

mcp-manager> daemon start
MCP Manager daemon started (PID: 12345) on port 4123

mcp-manager> server list
┏━━━━━━━━━━━━┳━━━━━━━━━━┓
┃    Name    ┃  Status  ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━┩
┃ hackernews ┃  running ┃
└──────────━━┴─────────━┘

mcp-manager> api-key
Current API Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

mcp-manager> help
[Shows the list of available commands]

Available CLI Commands

Command	Description
daemon start [--port PORT]	Start the MCP Manager daemon (optionally on a custom port)
daemon stop	Stop the MCP Manager daemon
daemon status	Show daemon status
daemon log	Show the last N lines of the daemon log file
server list	List all managed servers (shows Name and Status)
server reload	Reload the MCP servers from the config file
server remove	Remove a managed server
server start	Start a managed server
server stop	Stop a managed server
tools list	List all tools
api-key	Show the current API key
regenerate-api-key	Regenerate and show a new API key
config edit	Edit the MCP config JSON in your preferred editor (with JSON validation)
clear	Clear the screen
exit	Exit the CLI

Note:

• daemon start runs the server on port 4123 by default. Use --port <PORT> to specify a different port.
• All config and runtime files are stored in .cache/.
• The config edit command opens .cache/mcp_config.json in your preferred editor (set by $EDITOR, or falls back to vim/nano/notepad) and checks for valid JSON before saving.

Daemon Log

• The daemon log file is stored at .cache/mcp_manager_daemon.log.
• Use the daemon log command to view the last N lines of the log.

Using with ngrok

Use ngrok to share your local MCP Manager server publicly:

# In another terminal:
ngrok http 4123

Using with Cursor

Use supergateway to connect with Cursor. Update the port and API key as needed:

{
  "mcpServers": {
    "mcp-manager": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "http://localhost:YOUR_PORT/sse",
        "--oauth2Bearer",
        "YOUR-API-KEY"
      ]
    }
  }
}

Replace YOUR_PORT with the port used by daemon start (default 4123), and YOUR-API-KEY with the value from .cache/mcp_manager_api_key.txt or the api-key command.

Roadmap

• Support Multi-Tenant

License

MIT License