AI导哈

MCP服务器管理工具

一个命令行工具，用于管理兼容Model Context Protocol (MCP)的服务器，支持发现、安装和配置MCP服务器，适用于Claude Code等多种客户端。

  • by brandon-fryslie
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 brandon-fryslie/mcpi

使用说明

MCP经理（mcpi）

一种命令行工具，用于跨不同的MCP兼容客户端管理模型上下文协议（MCP）服务器。轻松发现、安装和配置用于Claude Code和其他兼容工具的MCP服务器。

特性

  • 综合注册表：包含元数据的已知MCP服务器目录
  • 配置模板：交互式设置，带有常见服务器的引导提示
  • 多目录支持：官方目录+您当地的定制目录
  • 基于范围的配置：跨多个配置范围（项目级、用户级）管理服务器
  • 多客户端支持：适用于Claude Code、Cursor、VS Code和其他MCP客户端
  • CLI接口：直观的命令行界面，带有shell选项卡完成功能
  • 插件架构：支持新MCP客户端的可扩展客户端插件系统

安装

使用uvx（推荐）

uvx mcpi

使用紫外线

uv tool install mcpi

开发安装

git clone https://github.com/user/mcpi
cd mcpi
uv sync
source .venv/bin/activate

macOS iCloud Drive用户注意事项：如果您的项目在iCloud Drive中，请使用 .venv.nosync 以避免间歇性的导入问题。看 故障排除 了解详情。

快速开始

发现MCP服务器

# Search for specific functionality
mcpi search --query filesystem

# Get detailed information about a server (shows registry + install status)
mcpi info filesystem

配置模板

MCPI v0.5.0+包含配置模板，通过交互式提示指导您完成服务器设置，将配置时间从15-30分钟缩短到2-3分钟。

模板快速入门

# List available templates for a server
mcpi add postgres --list-templates

# Use a template interactively
mcpi add postgres --template local-development
Database name to connect to [postgres]: myapp_dev
Database username (leave empty for peer authentication) []:
✓ Server 'postgres' added successfully

可用模板

PostgreSQL （3个模板）：

  • local-development：用于开发的本地PostgreSQL数据库
  • docker：PostgreSQL在Docker容器中运行
  • production：具有完整连接详细信息的生产数据库

GitHub （3个模板）：

  • personal-full-access：完全访问私有和公共存储库
  • read-only：对存储库的只读访问
  • public-repos：仅限公共存储库（不需要令牌）

文件系统 （3个模板）：

  • project-files：访问当前项目目录
  • user-documents：访问~/Documents目录
  • custom-directories：具有多个路径的自定义目录访问

Slack （2个模板）：

  • bot-token：用于自动操作的Slack机器人
  • limited-channels：Bot仅限于特定频道

勇敢的搜索 （1个模板）：

  • api-key：勇敢地用你的API密钥搜索API

模板功能

  • 互动提示：逐步指导设置和验证
  • 秘密面具：输入过程中隐藏的密码和API密钥（例如********）
  • 智能默认值：预填充通用值，以加快设置速度
  • 实时验证：输入验证，并显示有用的错误消息
  • 安装说明：每个模板都包括详细的说明和示例
  • 内置安全功能：令牌、密钥和URL的格式检查

模板示例

示例1：PostgreSQL本地开发

$ mcpi add postgres --template local-development

Using template 'local-development' for server 'postgres'
Scope: user-global

Template Notes:
  This template creates a PostgreSQL connection URL for local development.

  Connection URL format: postgresql://[user@]localhost/database

  If you leave the username empty, PostgreSQL will use peer authentication
  (your OS username). This is common for local development on macOS/Linux.

Database name to connect to (e.g., 'myapp_dev') [postgres]: myapp_dev
Database username (leave empty for peer authentication) []:

✓ Server 'postgres' added to user-global scope

示例2：带有个人访问令牌的GitHub

$ mcpi add github --template personal-full-access

Using template 'personal-full-access' for server 'github'
Scope: user-global

GitHub Personal Access Token: ****************************************

✓ Server 'github' added to user-global scope

示例3：文件系统访问

$ mcpi add filesystem --template project-files

Using template 'project-files' for server 'filesystem'
Scope: project-mcp

Project root directory [/Users/alice/projects/myapp]:

✓ Server 'filesystem' added to project-mcp scope

多个目录

MCPI v0.4.0+支持多个目录来组织MCP服务器：

查看可用目录

# List all catalogs
mcpi catalog list

# View catalog details
mcpi catalog info official
mcpi catalog info local

跨目录搜索

# Search official catalog (default)
mcpi search --query filesystem

# Search local catalog
mcpi search --query myserver --catalog local

# Search specific catalog explicitly
mcpi search --query database --catalog official

使用本地目录

将自定义服务器添加到您的本地目录 ~/.mcpi/catalogs/local/catalog.json:

# Add a server definition to local catalog
# Then use it with --catalog local flag
mcpi add myserver --catalog local --scope user-global

您的本地目录与官方目录是分开的，因此您的自定义设置不会受到更新的影响。

常见问题解答

Q： 我的本地目录存储在哪里？ A. ~/.mcpi/catalogs/local/catalog.json （首次使用时自动创建）

Q： 我可以有两个以上的目录吗？ A： 不在v0.4.0（第1阶段）中。第二阶段将添加基于git的远程目录。

Q： 我现有的命令仍然有效吗？ A： 是的！100%向后兼容。--catalog标志是可选的。

管理已安装的服务器

# List currently installed servers
mcpi list

# List servers in a specific scope
mcpi list --scope user-global

# List servers for a specific client
mcpi list --client claude-code

# Add a server (interactive scope selection)
mcpi add filesystem

# Add a server to a specific scope
mcpi add filesystem --scope project-mcp

# Remove a server
mcpi remove filesystem

# Check system status
mcpi status

范围管理

# List available scopes for the default client
mcpi scope list

# List scopes for a specific client
mcpi scope list --client claude-code

# Consolidate a server to a specific scope (removes from all other scopes)
mcpi rescope filesystem --to user-global

客户管理

# List detected MCP clients
mcpi client list

# Get information about a specific client
mcpi client info claude-code

# Set the default client
mcpi client set-default claude-code

Shell选项卡完成

# Enable tab completion for bash
mcpi completion --shell bash

# Enable tab completion for zsh
mcpi completion --shell zsh

# Enable tab completion for fish
mcpi completion --shell fish

建筑

MCPI使用 基于范围的配置系统 带着一个 插件架构 用于支持多个MCP客户端。

基于范围的配置

代替传统的基于配置文件的配置，mcpi使用 范围 它们是具有不同优先级的分层配置级别。每个MCP客户端都定义了自己的作用域。

示例范围（克劳德代码）

作用域名称 类型 优先级 描述
project-mcp 项目 10 项目级 .mcp.json （最高优先级）
project-local 项目 20 本地项目 .claude/settings.local.json
project-internal 项目 30 项目内部 .claude/settings.json
user-internal 用户 40 用户内部 ~/.claude/settings.json
user-global 用户 50 用户全局 ~/.config/claude/settings.json
user-local 用户 60 本地用户 ~/.claude/settings.local.json （最低优先级）

优先权制度：较低优先级的数字会覆盖较高优先级的数字。项目级范围覆盖用户级范围。

插件架构

每个MCP客户端（Claude Code、Cursor、VS Code）都实现为 插件 这符合 MCPClientPlugin 协议：

  • 客户端检测：自动检测已安装的客户端
  • 作用域处理程序：每个作用域都由一个处理程序管理，该处理程序知道如何读取/写入特定的配置文件
  • 架构验证：根据客户端特定的架构验证配置更改
  • 可扩展：易于添加对新MCP客户端的支持

CLI命令

目录管理命令

mcpi catalog list

列出所有可用的目录。

mcpi catalog list

mcpi catalog info <name>

显示有关目录的详细信息。

mcpi catalog info official
mcpi catalog info local

发现命令

mcpi search --query <query>

在注册表中按名称或描述搜索服务器。

选项：

  • --query, -q TEXT：搜索查询（必填）
  • --catalog TEXT：搜索特定目录（官方或本地，默认：官方）
mcpi search --query filesystem
mcpi search -q database --catalog local
mcpi search --query git --catalog official

备注：v0.4.0将搜索语法从position更改为--query标志，以与多目录功能兼容。

mcpi info <server-id>

显示有关服务器的详细信息，包括注册表信息和本地安装状态。

选项：

  • --catalog TEXT：在特定目录中查找服务器
mcpi info filesystem
mcpi info brave-search
mcpi info my-server --catalog local

交互界面

mcpi fzf

启动用于管理MCP服务器的交互式模糊查找器界面。

特征：

  • 使用模糊搜索浏览注册表中的所有服务器
  • 顶部显示已安装的服务器（绿色=已启用，黄色=已禁用）
  • 不退出的交互式操作（添加、删除、启用、禁用）
  • 预览窗格显示服务器详细信息
  • 操作后刷新列表以显示更新的状态

键盘快捷键：

  • ctrl-a：将服务器添加到配置中
  • ctrl-r：从配置中删除服务器
  • ctrl-e：启用服务器
  • ctrl-d：禁用服务器
  • ctrl-i / enter：显示详细信息
  • esc / ctrl-c：退出

要求：

  • 需要 fzf 待安装(brew install fzf 在macOS上， apt install fzf 在Ubuntu上）

例子：

# Launch interactive interface
mcpi fzf

服务器管理命令

mcpi list [OPTIONS]

列出已安装的MCP服务器。

选项：

  • --client TEXT：按客户端筛选（如果未指定，则使用默认值）
  • --scope TEXT：按作用域筛选（可用作用域取决于客户端）
  • --state TEXT：按状态筛选（启用、禁用、未安装）
  • --verbose, -v：显示详细信息

示例：

# List all installed servers
mcpi list

# List servers in a specific scope
mcpi list --scope user-global

# List servers for a specific client
mcpi list --client claude-code

# List only enabled servers
mcpi list --state enabled

# Show detailed information
mcpi list --verbose

mcpi add <server-id> [OPTIONS]

从注册表中添加MCP服务器。

选项：

  • --client TEXT：目标客户端（如果未指定，则使用默认值）
  • --scope TEXT：目标范围（如果未指定，则进行交互式选择）
  • --catalog TEXT：源目录（官方或地方）
  • --template TEXT：使用配置模板进行引导设置
  • --list-templates：显示此服务器的可用模板
  • --dry-run：显示在不进行更改的情况下会做什么

示例：

# Add a server (interactive scope selection)
mcpi add filesystem

# List available templates for a server
mcpi add postgres --list-templates

# Add server using a template (interactive prompts)
mcpi add postgres --template local-development

# Add to a specific scope
mcpi add filesystem --scope project-mcp

# Add from local catalog
mcpi add myserver --catalog local --scope user-global

# Preview without making changes
mcpi add filesystem --dry-run

mcpi remove <server-id> [OPTIONS]

卸下MCP服务器。

选项：

  • --client TEXT：目标客户端（如果未指定，则使用默认值）
  • --scope TEXT：源范围（如果未指定，则自动检测）
  • --dry-run：显示在不进行更改的情况下会做什么

示例：

# Remove a server (prompts for confirmation)
mcpi remove filesystem

# Remove from a specific scope
mcpi remove filesystem --scope project-mcp

mcpi enable <server-id> [OPTIONS]

启用已禁用的MCP服务器。

选项：

  • --client TEXT：目标客户端（如果未指定，则使用默认值）
  • --dry-run：显示在不进行更改的情况下会做什么

示例：

mcpi enable filesystem

mcpi disable <server-id> [OPTIONS]

禁用已启用的MCP服务器。

选项：

  • --client TEXT：目标客户端（如果未指定，则使用默认值）
  • --dry-run：显示在不进行更改的情况下会做什么

示例：

mcpi disable filesystem

mcpi rescope <server-name> --to <scope> [OPTIONS]

将MCP服务器配置整合到特定范围，自动将其从所有其他范围中删除。

选项：

  • --to TEXT：目标范围（必填）
  • --client TEXT：要使用的MCP客户端（如果未指定，则自动检测）
  • --dry-run：显示不进行更改会发生什么

示例：

# Consolidate server to user-global scope (removes from all other scopes)
mcpi rescope filesystem --to user-global

# Preview the operation
mcpi rescope filesystem --to user-global --dry-run

# Specify a client explicitly
mcpi rescope filesystem --to user-global --client claude-code

它是如何工作的：

  1. 自动检测服务器当前配置的所有作用域
  2. 将服务器添加到目标作用域（如果已有配置，则保留现有配置）
  3. 从所有其他作用域中删除服务器
  4. 操作是原子性的：首先添加到目标，然后从源中删除（防止数据丢失）

笔记：

  • 幂等：可以安全地多次运行-无论当前状态如何，都可以整合到目标范围
  • 自动检测：无需指定源范围-自动查找所有范围
  • 安全：如果服务器已经在目标作用域中，则保留目标配置并清理其他作用域
  • 多范围清理：如果服务器分散在多个作用域中，则合并到单个目标作用域

mcpi info [server-id] [OPTIONS]

显示有关服务器或系统状态的详细信息。

选项：

  • --client TEXT：目标客户端（如果未指定，则使用默认值）
  • --catalog TEXT：在特定目录中查找服务器

示例：

# Show system status
mcpi info

# Show server information
mcpi info filesystem

# Show server from local catalog
mcpi info myserver --catalog local

范围管理命令

mcpi scope list [OPTIONS]

列出可用的配置范围。

选项：

  • --client TEXT：按客户端筛选（如果未指定，则使用默认值）

示例：

# List scopes for default client
mcpi scope list

# List scopes for a specific client
mcpi scope list --client claude-code

客户端管理命令

mcpi client list

列出可用的MCP客户端。

mcpi client list

mcpi client info [client-name]

显示有关客户的详细信息。

# Show default client info
mcpi client info

# Show specific client info
mcpi client info claude-code

mcpi client set-default <client-name>

设置MCPI操作的默认客户端。

mcpi client set-default claude-code

系统命令

mcpi status

显示系统状态和摘要信息。

mcpi status

mcpi completion --shell <shell>

为mcpi生成shell完成脚本。

选项卡完成为以下内容提供了智能建议：

  • 命令名称（列表、添加、删除等）
  • 选项标志（--client、--scope、--help）
  • 客户端名称（基于检测到的MCP客户端）
  • 作用域名称（按所选客户端筛选）
  • 服务器ID（来自注册表）

选项：

  • --shell TEXT：外壳类型（bash、zsh、fish）-如果未指定，则自动检测

示例：

# Auto-detect shell and show instructions
mcpi completion

# Generate bash completion
mcpi completion --shell bash

# Generate zsh completion
mcpi completion --shell zsh

# Generate fish completion
mcpi completion --shell fish

安装：

对于 bash，添加到 ~/.bashrc:

eval "$(_MCPI_COMPLETE=bash_source mcpi)"

对于 Z shell，添加到 ~/.zshrc:

eval "$(_MCPI_COMPLETE=zsh_source mcpi)"

对于 鱼，添加到 ~/.config/fish/config.fish:

eval (env _MCPI_COMPLETE=fish_source mcpi)

MCP服务器注册表

注册表包含有关可用MCP服务器的信息，包括：

  • 基本信息：名称、描述、存储库
  • 安装细节：运行服务器所需的命令和参数
  • 分类：易于发现的分类（填充时）

注册表格式

注册表存储在 data/registry.json 具有以下结构：

{
  "server-id": {
    "description": "Brief description of server functionality",
    "command": "npx",
    "args": ["-y", "@package/mcp-server"],
    "repository": "https://github.com/org/repo",
    "categories": ["category1", "category2"]
  }
}

将服务器添加到注册表

要将新的MCP服务器添加到注册表中，请执行以下操作：

  1. 编辑 data/registry.json
  2. 添加包含服务器详细信息的新条目
  3. 确保命令和参数正确
  4. 可选择添加分类类别
  5. 提交拉取请求

支持的MCP服务器

核心服务器（Anthropic）

  • 文件系统：本地文件系统操作
  • SQLite：SQLite数据库操作
  • 勇敢的搜寻：通过Brave search API进行网络搜索
  • 获取：发出HTTP请求并获取web内容
  • GitHub：与GitHub存储库、问题和拉取请求交互

社区服务器

注册表包含其他社区贡献的服务器。使用 mcpi search 查找可用服务器。

与Claude Code的集成

mcpi提供了与Claude Code的无缝集成：

自动检测：mcpi会自动检测Claude Code安装并适当配置MCP服务器。

多个配置范围：Claude Code支持6种不同的配置范围，从项目级到用户级。

配置管理：通过适当的验证直接更新Claude Code的配置文件。

Claude代码集成示例：

# Add filesystem server to project scope
mcpi add filesystem --scope project-mcp

# This updates .mcp.json in your project:
# {
#   "mcpServers": {
#     "filesystem": {
#       "command": "npx",
#       "args": ["-y", "@anthropic/mcp-server-filesystem"]
#     }
#   }
# }

发展

项目结构

mcpi/
├── src/mcpi/              # Source code
│   ├── cli.py            # CLI interface
│   ├── clients/          # Client plugins
│   │   ├── base.py       # Base protocols and types
│   │   ├── manager.py    # MCPManager orchestration
│   │   ├── claude_code.py # Claude Code plugin
│   │   └── file_based.py # File-based scope implementations
│   ├── registry/         # Server registry
│   │   ├── catalog.py    # Server catalog and models
│   │   └── catalog_manager.py # Multi-catalog management
│   └── templates/        # Configuration templates
│       ├── models.py     # Template data models
│       ├── template_manager.py # Template loading
│       └── prompt_handler.py # Interactive prompts
├── data/                 # Registry data
│   ├── catalog.json      # Server definitions
│   └── templates/        # Template YAML files
│       ├── postgres/
│       ├── github/
│       ├── filesystem/
│       ├── slack/
│       └── brave-search/
└── tests/                # Test suite

开发设置

git clone https://github.com/user/mcpi
cd mcpi
uv sync --dev
source .venv/bin/activate

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src/mcpi

# Run specific test file
pytest tests/test_registry_categories.py

# Validate registry data
pytest tests/test_registry_integration.py -v

代码质量

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/ --fix

# Type checking
mypy src/

贡献

为注册表做出贡献

要将新的MCP服务器添加到注册表中，请执行以下操作：

  1. 复刻仓库
  2. 将服务器详细信息添加到 data/registry.json
  3. 测试服务器条目： mcpi info <your-server-id>
  4. 提交拉取请求

服务器条目格式

{
  "your-server-id": {
    "description": "Brief description of functionality",
    "command": "npx",
    "args": ["-y", "@package/your-mcp-server"],
    "repository": "https://github.com/user/repo",
    "categories": ["category1", "category2"]
  }
}

贡献模板

要添加配置模板，请执行以下操作：

  1. 在中创建一个YAML文件 data/templates/<server-id>/<template-name>.yaml
  2. 遵循模板结构（参见 docs/TEMPLATE_AUTHORING_GUIDE.md)
  3. 测试模板： mcpi add <server-id> --template <template-name>
  4. 提交拉取请求

看 docs/TEMPLATE_AUTHORING_GUIDE.md 了解详细的模板编写指南。

开发指南

  • 遵循PEP 8风格指南
  • 为所有函数添加类型提示
  • 为新功能编写测试
  • 更新新功能的文档
  • 使用语义版本控制

Python API

MCPI可以用作编程MCP服务器管理的Python库。

基本用法

from mcpi.registry.catalog_manager import create_default_catalog_manager
from mcpi.clients.manager import create_default_manager

# Create catalog manager to browse available servers
catalog_manager = create_default_catalog_manager()
official_catalog = catalog_manager.get_catalog("official")
official_catalog.load_registry()

# Search for servers
results = official_catalog.search_servers("filesystem")
for server_id, server in results:
    print(f"{server_id}: {server.description}")

# Create manager for server operations
manager = create_default_manager()

# List installed servers
servers = manager.list_servers()
for server_id, info in servers.items():
    print(f"{server_id}: {info.state}")

# Add a server
result = manager.add_server(
    "filesystem",
    config={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"]},
    scope="user-global"
)
print(result.message)

工厂功能（推荐）

对于生产使用，使用处理默认初始化的工厂函数：

from mcpi.registry.catalog_manager import (
    create_default_catalog_manager,
    create_test_catalog_manager
)
from mcpi.clients.manager import create_default_manager, create_test_manager

# Production: Use defaults
catalog_manager = create_default_catalog_manager()  # Uses data/catalog.json
manager = create_default_manager()  # Auto-detects clients

# Testing: Inject dependencies
from pathlib import Path
test_catalog_manager = create_test_catalog_manager(
    official_path=Path("/tmp/official.json"),
    local_path=Path("/tmp/local.json")
)
test_manager = create_test_manager(mock_registry)

重大更改（v2.0）

重要：MCPI v2.0引入了依赖注入，以提高可测试性：

# OLD API (no longer works):
from mcpi.registry.catalog import ServerCatalog
from mcpi.clients.manager import MCPManager
catalog = ServerCatalog()  # TypeError: missing required argument 'registry_path'
manager = MCPManager()      # TypeError: missing required argument 'registry'

# NEW API (use factory functions):
from mcpi.registry.catalog import create_default_catalog
from mcpi.clients.manager import create_default_manager
catalog = create_default_catalog()  # Provides default path
manager = create_default_manager()  # Creates default registry

# NEW API (explicit injection for advanced use):
from mcpi.registry.catalog import ServerCatalog
from mcpi.clients.manager import MCPManager
from mcpi.clients.registry import ClientRegistry
from pathlib import Path

catalog = ServerCatalog(registry_path=Path("custom/registry.json"))
manager = MCPManager(registry=ClientRegistry())

迁移指南:

  • 替换 ServerCatalog() 随着 create_default_catalog()
  • 替换 MCPManager() 随着 create_default_manager()
  • 为了进行测试，请使用 create_test_catalog(path) 和 create_test_manager(registry)
  • 对于高级使用，显式传递必需的参数

为什么会有这种变化？ 依赖反转原理（DIP）实现了：

  • 真正的单元测试，无需文件系统访问
  • 组件隔离和模块化
  • 在测试中更容易模仿
  • 更好地遵守SOLID原则

重大变化（v0.4.0）

搜索命令语法：从位置更改为--查询标志：

# OLD (v0.3.0)
mcpi search filesystem

# NEW (v0.4.0)
mcpi search --query filesystem
# or
mcpi search -q filesystem

所有其他命令保持不变。

故障排除

常见问题

添加后服务器未显示：

# Check if server was added successfully
mcpi list --verbose

# Check specific scope
mcpi list --scope project-mcp

找不到默认客户端：

# List available clients
mcpi client list

# Set default client manually
mcpi client set-default claude-code

未找到作用域：

# List available scopes
mcpi scope list

# Check scope existence in current directory
mcpi scope list --client claude-code

选项卡完成不起作用：

# Re-run the completion setup
mcpi completion --shell bash

# Make sure to source your shell config
source ~/.bashrc  # or ~/.zshrc for zsh

导入开发中的错误（macOS iCloud Drive）：

如果在iCloud Drive中开发，您可能会遇到间歇性 ModuleNotFoundError: No module named 'mcpi' 由于iCloud设置了隐藏标志 .pth 文件夹。

解决方案1：使用.venv.nosync（建议用于开发）

cd ~/path/to/mcpi

# Remove existing venv
rm -rf .venv

# Create .venv.nosync (excluded from iCloud sync)
python -m venv .venv.nosync
ln -s .venv.nosync .venv

# Install in editable mode
source .venv/bin/activate
pip install -e .

这 .nosync 后缀告诉iCloud将目录从同步中排除，防止隐藏的标志问题。

解决方案2：使用UV工具安装（建议用于CLI）

# Install as UV tool (stored in ~/.local/, not in iCloud)
uv tool install --editable ~/path/to/mcpi

# Use from anywhere without venv activation
mcpi --help

# For testing
cd ~/path/to/mcpi
pytest  # Uses pythonpath from pyproject.toml

紧急修复（临时）：

# Remove hidden flags manually
./scripts/fix-pth-flags.sh

# Or manually:
cd ~/path/to/mcpi
chflags nohidden .venv/lib/python3.*/site-packages/*.pth

看 .agent_planning/ICLOUD-COMPATIBLE-FIX-2025-10-30.md 了解技术细节。

获取帮助

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

致谢

备注：此工具管理MCP服务器配置。它不安装底层的npm/pip包——当MCP客户端（如Claude Code）首次使用服务器时，这些包会自动安装。

相关 MCP