Mcphub

MCP Hub

The package manager for Model Context Protocol servers.

Search, install, and manage MCP servers with a single command.

[](https://go.dev) [](LICENSE) [](https://www.npmjs.com/package/@ricardo.m.lu/mcphub) [](https://github.com/Ricardo-M-L/mcphub/releases) [](https://github.com/Ricardo-M-L/mcphub/actions)

mcphub search filesystem
mcphub install io.github.user/server-filesystem
mcphub doctor   # ← diagnose broken MCP servers

Works with: Claude Code · Claude Desktop · Cursor

Features

• One-command install - Install any MCP server and auto-configure your clients
• Smart detection - Automatically finds Claude Desktop, Cursor, and other MCP clients
• Registry search - Browse the entire MCP server ecosystem from your terminal
• MCP server mode - Use mcphub as an MCP service inside Claude Code or Cursor
• Zero config - Works out of the box with sensible defaults
• Safe config updates - Backs up your config files before modifying them
• Cross-platform - macOS, Linux, and Windows support
• Single binary - No runtime dependencies

---

Installation

Choose any method:

curl (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/Ricardo-M-L/mcphub/master/install.sh | sh

Homebrew

brew tap Ricardo-M-L/mcphub
brew install mcphub

npm

npm install -g @ricardo.m.lu/mcphub

Go

go install github.com/Ricardo-M-L/mcphub/cmd/mcphub@latest

From source

git clone https://github.com/Ricardo-M-L/mcphub.git
cd mcphub
make build
# Binary at ./bin/mcphub

---

Usage

Search for MCP servers

mcphub search filesystem
mcphub search database
mcphub search github
mcphub search slack

# JSON output
mcphub search filesystem --json

# Limit results
mcphub search database --limit 5

View server details

mcphub info io.github.user/server-filesystem
mcphub info io.github.user/server-filesystem --json

Install an MCP server

mcphub install io.github.user/server-filesystem

What happens when you run install:

1. Queries the MCP Registry for the server
2. Determines the install method (npm/npx or remote URL)
3. Prompts for required environment variables (API keys, etc.)
4. Auto-detects installed MCP clients (Claude Desktop, Cursor)
5. Writes the server config into each client's config file (with backup)
6. Records the install in ~/.mcphub/mcphub-lock.json

Target a specific client:

mcphub install io.github.user/server-filesystem --client claude-desktop
mcphub install io.github.user/server-filesystem --client cursor

List installed servers

mcphub list
mcphub list --json

Remove a server

mcphub remove io.github.user/server-filesystem

This removes the server from all configured MCP clients and the lockfile.

Publish your own MCP server

If you've built an MCP server and want others to install it via mcphub, follow these steps:

1. Publish your MCP server to npm

cd my-mcp-server
npm publish --access public

After publishing, anyone can run your server with npx @your-scope/my-mcp-server.

2. Create a mcphub manifest

mcphub init

This generates a mcphub.json file. Edit it with your server's info:

{
  "name": "your-org/my-mcp-server",
  "version": "1.0.0",
  "description": "What your MCP server does",
  "runtime": {
    "type": "npm",
    "command": "npx",
    "package": "@your-scope/my-mcp-server"
  },
  "transport": "stdio",
  "environmentVariables": [
    {
      "name": "API_KEY",
      "description": "Your API key for the service",
      "required": true,
      "secret": true
    }
  ]
}

3. Validate and publish

# Validate without publishing
mcphub publish --dry-run

# Publish to MCP Registry
mcphub publish

4. Now anyone can install your server

# Search for it
mcphub search my-mcp-server

# Install (auto-configures Claude Desktop / Cursor)
mcphub install your-org/my-mcp-server

# Or add directly to Claude Code
claude mcp add my-server npx @your-scope/my-mcp-server

Supported transport types

| Transport | How it works | User downloads? | Example | |-----------|-------------|-----------------|---------| | stdio | Local process via npx | Yes (npm package) | npx @scope/my-server | | streamable-http | Remote HTTP endpoint | No, just connects to URL | https://api.example.com/mcp | | sse | Server-Sent Events endpoint | No, just connects to URL | https://api.example.com/sse |

For remote servers (streamable-http / sse), set your mcphub.json like this:

{
  "name": "your-org/my-remote-server",
  "version": "1.0.0",
  "description": "My remote MCP server",
  "transport": "streamable-http",
  "remoteUrl": "https://api.example.com/mcp"
}

Users install the same way — mcphub auto-detects the transport type:

mcphub install your-org/my-remote-server
# → Configures URL in Claude Desktop / Cursor, zero download

Distribution options

| Method | What you do | How users install | Best for | |--------|------------|-------------------|----------| | npm + stdio | npm publish + mcphub publish | mcphub install xxx | CLI tools, local servers | | Remote URL | Deploy server + mcphub publish | mcphub install xxx (zero download) | API services, cloud MCP | | Direct | npm publish only | claude mcp add xxx npx @scope/pkg | Simple, no registry |

---

Use as MCP Service (Claude Code / Cursor)

mcphub can run as an MCP server itself, so you can search and install MCP servers directly from your AI assistant.

Quick Setup (2 commands)

# Install the MCP server binary
go install github.com/Ricardo-M-L/mcphub/mcp@latest

# Add to Claude Code
claude mcp add mcphub mcphub-mcp

That's it. Restart Claude Code and start chatting.

Alternative: Build from source

git clone https://github.com/Ricardo-M-L/mcphub.git
cd mcphub
go build -o bin/mcphub-mcp ./mcp
claude mcp add mcphub /path/to/mcphub/bin/mcphub-mcp

Other MCP clients

Or manually add to ~/.claude/settings.json:

{
  "mcpServers": {
    "mcphub": {
      "command": "/path/to/mcphub-mcp"
    }
  }
}

Claude Desktop - Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcphub": {
      "command": "/path/to/mcphub-mcp"
    }
  }
}

Cursor - Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcphub": {
      "command": "/path/to/mcphub-mcp"
    }
  }
}

3. Use in conversation

After restarting your client, you can say things like:

• "Search for database MCP servers"
• "Install the filesystem MCP server"
• "What MCP servers do I have installed?"
• "Remove the github MCP server"

Available MCP Tools

| Tool | Description | |------|-------------| | search_servers | Search the MCP registry for servers | | install_server | Install a server and auto-configure clients | | list_installed | List all installed MCP servers | | remove_server | Remove a server from all clients | | server_info | Get detailed info about a server |

---

How It Works

                                    MCP Registry
                                  (registry.modelcontextprotocol.io)
                                         |
                                    HTTP API
                                         |
    Terminal ──── mcphub CLI ────────────┤
                      |                  |
                      |            Search / Info
                      |
                Install / Remove
                      |
            ┌─────────┼─────────┐
            |         |         |
      Claude       Cursor    Claude
      Desktop                  Code
            |         |         |
        config     config    config
         .json      .json    .json

• mcphub does NOT download packages - For npm-based servers, it writes npx -y into your client config. npx handles download and caching at runtime.
• mcphub does NOT run MCP servers - It only configures your MCP clients to run them.
• Config safety - Always creates .bak backups before modifying config files.
• Lockfile - Tracks installed servers at ~/.mcphub/mcphub-lock.json.

---

Supported MCP Clients

| Client | Config Path | Auto-detect | |--------|------------|-------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | Yes | | Cursor | ~/.cursor/mcp.json | Yes | | Claude Code | ~/.claude/settings.json | Planned | | OpenCode | opencode.json | Planned |

---

Project Structure

mcphub/
├── cmd/mcphub/          # CLI entrypoint
├── mcp/                 # MCP server mode (stdio transport)
├── internal/
│   ├── cli/             # Command definitions (search, install, list, remove, info, publish)
│   ├── registry/        # MCP Registry API client
│   ├── installer/       # Package installers (npm, remote)
│   ├── config/          # MCP client config read/write (with backup)
│   ├── store/           # Local lockfile management
│   ├── ui/              # Terminal output formatting
│   └── platform/        # OS-specific file paths
├── server/              # Registry API server (Go + SQLite + FTS5)
│   ├── handler/         # REST API handlers
│   ├── crawler/         # Upstream registry sync
│   └── db/              # SQLite with full-text search
├── web/                 # Web UI (Next.js + TypeScript)
├── npm/                 # npm package wrapper
├── install.sh           # curl installer script
├── Dockerfile           # Container build
├── Makefile             # Build targets
└── .github/workflows/   # CI/CD + Release automation

---

Development

Prerequisites

• Go 1.23+
• Node.js 20+ (for web UI)

Build

# CLI
make build

# MCP server
go build -o bin/mcphub-mcp ./mcp

# Registry API server
go build -o bin/mcphub-server ./server

# Web UI
cd web && npm install && npx next build

Test

make test

Run locally

# CLI
./bin/mcphub search filesystem

# MCP server (stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./bin/mcphub-mcp

# Registry API server
./bin/mcphub-server --port 8080

---

Roadmap

• [x] CLI: search, install, list, remove, info, publish, init
• [x] Auto-configure Claude Desktop and Cursor
• [x] MCP server mode for Claude Code / Cursor integration
• [x] Registry API server with SQLite + FTS5 full-text search
• [x] Web UI for browsing MCP servers
• [x] Quality scoring API (completeness, installability, documentation, security)
• [x] CI/CD with GitHub Actions + cross-platform release builds
• [x] 5 distribution methods: curl, Homebrew, npm, Go, source
• [x] 14 unit tests passing
• [x] Claude Code & Windsurf auto-detection support
• [x] SDK auto-generation from MCP tool schemas (TypeScript & Python)
• [x] Server health monitoring (mcphub doctor)
• [x] Community ratings and reviews (mcphub rate & ratings)

---

Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

License

Apache-2.0 - see [LICENSE](LICENSE) for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Ricardo-M-L
• Source: Ricardo-M-L/mcphub
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.