cursor-mcp 0.1.0

MCP server for managing Cursor IDE MCP configurations

Cursor MCP Manager

An MCP (Model Context Protocol) server that allows you to manage Cursor IDE's MCP configuration through tools.

Features

• List MCP Servers: View all configured MCP servers
• Add MCP Server: Add new MCP servers to your configuration (STDIO or HTTP)
• Remove MCP Server: Remove existing MCP servers
• Update MCP Server: Modify server configurations
• Refresh Server: Restart a specific MCP server with automatic process cleanup
• Kill Server: Manually stop a running MCP server
• Process Monitoring: Check server status and running processes
• Log Collection: View logs from running MCP servers
• Cross-Platform: Works on Windows, macOS, and Linux
• Docker Support: Special handling for Docker-based MCP servers

Note: Cursor automatically detects changes to the mcp.json file and reloads servers without requiring a restart.

Installation

Quick Install with uvx (Recommended)

The simplest way to use cursor-mcp is with uvx (no installation required!):

{
  "mcpServers": {
    "cursor-manager": {
      "command": "uvx",
      "args": ["cursor-mcp"]
    }
  }
}

That's it! This will automatically download and run the latest version from PyPI.

Alternative: Install from Source

If you want to run from source code:

{
  "mcpServers": {
    "cursor-manager": {
      "command": "uv",
      "args": [
        "--directory",
        "path\\to\\hud-cursor-manager",
        "run",
        "mcp-stdio"
      ]
    }
  }
}

How it Works

1. First Connection: When Cursor starts the STDIO proxy, it automatically spawns a persistent HTTP server in the background
2. Subsequent Connections: New Cursor windows connect to the existing HTTP server
3. Shared State: All windows share the same server state, logs, and configuration
4. Persistence: The HTTP server continues running even after all Cursor windows are closed

MCP Protocol Compliance

The cursor-mcp-manager follows the MCP specification:

• JSON-RPC 2.0: All messages use standard JSON-RPC format
• Lifecycle Management: Proper handling of initialize, initialized, and shutdown messages
• STDIO Transport: The proxy handles stdin/stdout communication with proper message framing
• HTTP Transport: The backend server uses HTTP/SSE for multi-client support
• Error Handling: Implements proper JSON-RPC error codes (-32700 for parse errors, -32603 for internal errors)

The STDIO proxy acts as a bridge, converting between:

• Client → Server: STDIO messages are forwarded to the HTTP server via POST requests
• Server → Client: HTTP SSE events are forwarded to stdout
• Lifecycle: The proxy handles shutdown gracefully, disconnecting only the STDIO connection while keeping the HTTP server running

Managing the Background Server

The HTTP server runs persistently in the background. To manage it:

# Check server status
uv run cursor-manager status

# Stop the server
uv run cursor-manager stop

# Start the server manually
uv run cursor-manager start

# Restart the server
uv run cursor-manager restart

# View server logs
uv run cursor-manager logs

Important: The background HTTP server ignores shutdown signals when started by the STDIO proxy. This ensures it stays running even when Cursor disconnects. Use cursor-manager stop to properly shut it down.

Available Commands

Once installed, you can use these commands:

# Run the MCP server directly (same as default)
uvx cursor-mcp

# Use the manager CLI tool
uvx --from cursor-mcp cursor-manager

# Run the full server with HTTP backend
uvx --from cursor-mcp cursor-mcp-manager

Install from PyPI

# Install globally as a tool
uv tool install cursor-mcp

# Or use pip
pip install cursor-mcp

From source

git clone https://github.com/hud-evals/hud-cursor-manager
cd hud-cursor-manager
uv sync
uv run cursor-mcp-manager

Configuration

The Cursor MCP Manager runs as an HTTP server to share state across all Cursor windows.

Step 1: Start the HTTP Server

# From the project directory
uv run python start_http_server.py

# Or directly
uv run python -m cursor_mcp_manager

The server will run on http://localhost:8765

Step 2: Configure Cursor

Add this to your Cursor's MCP configuration at ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json):

{
  "mcpServers": {
    "cursor-manager": {
      "url": "http://localhost:8765"
    }
  }
}

Usage

Once configured, you can use the following tools in Cursor:

List all MCP servers

Ask: "List all my MCP servers"

Add a new server

Ask: "Add an MCP server named 'weather' with command 'python' and args ['weather_server.py']"

Remove a server

Ask: "Remove the MCP server named 'weather'"

Update a server

Ask: "Update the 'weather' server to use command 'uv' with args ['run', 'weather.py']"

Refresh/restart a specific server

Ask: "Refresh the 'weather' MCP server"

Check server status

Ask: "Is the 'weather' server running?"

View server logs

Ask: "Show me the logs for the 'weather' server"

Supported MCP Server Configurations

The Cursor MCP Manager supports all standard MCP server configuration options:

STDIO Servers (Command-based)

{
  "server-name": {
    "command": "python",
    "args": ["server.py", "--option", "value"],
    "env": {
      "API_KEY": "your-key",
      "DEBUG": "true"
    },
    "cwd": "/path/to/server/directory"
  }
}

HTTP/SSE Servers (URL-based)

{
  "remote-server": {
    "url": "http://example.com:8080/mcp"
  }
}

Docker-based Servers

{
  "docker-server": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-p", "6080:6080", "mcp/server-image"],
    "env": {
      "CONFIG": "production"
    }
  }
}

Platform-Specific Considerations

• Windows: The manager handles Windows paths and cmd.exe execution automatically
• macOS/Linux: Full support for Unix-style paths and shell commands
• Docker: Special handling for container lifecycle, including automatic cleanup on refresh

Development

# Install dependencies
uv sync

# Run the server
uv run cursor-mcp-manager

# Or run directly with Python
uv run python -m cursor_mcp_manager

Known Limitations

Tool List Updates in Active Conversations

When you refresh an MCP server that has new or updated tools, the changes will be available on your next message in the conversation. Cursor refreshes the tool list when you send a new message.

Note: Simply send another message after refreshing to see the updated tools - no need to start a new conversation.

License

MIT