内容
<p align="center">
<img src="assets/hero.png" alt="mcpctl - Claude 代码的 MCP 服务器管理器" width="800"/>
</p>
<p align="center">
<a href="https://pypi.org/project/mcp-ctrl/"><img src="https://img.shields.io/pypi/v/mcp-ctrl.svg" alt="PyPI 版本"></a>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="许可证：MIT"></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Compatible-green.svg" alt="MCP"></a>
<br><br>
每个启用的 MCP 服务器都会向您的上下文窗口注入其工具定义。<br>
启用 2-3 个服务器，您可能会损失超过 10 万个 tokens，仅用于工具模式。<br>
<strong>mcpctl</strong> 让您只需一个命令即可开关服务器。
</p>
---
支持全局（`~/.claude.json`）和项目（`.mcp.json`）范围，处理 Docker/Podman 服务器的容器生命周期，并为机密替换环境变量。
> **⚠️ 重要免责声明**
>
> MCP 服务器可以访问您的系统资源、文件和网络。**不同的服务器可能表现出不同的行为，并请求不同级别的机器访问权限。**
>
> **请自担风险。** 始终审查服务器权限，检查源代码库，并仅从受信任的来源启用服务器。
## ✨ 功能
- 🚀 **通用管理** - 适用于所有 MCP 服务器类型的单一工具（npm、python、docker）
- 🐳 **容器运行时自动检测** - 支持 Docker 和 Podman
- 📦 **包支持** - npm（npx）和 Python（uvx）包
- 🔐 **机密管理** - 来自 `.env` 文件的环境变量替换
- ⚡ **简单命令** - list、config、enable、disable
- 📝 **YAML 配置** - 人类可读的服务器定义
- 🔄 **自动备份** - 在更改之前备份 Claude 配置
## 📋 目录
- [安装](#-安装)
- [快速入门](#-快速入门)
- [用法](#-用法)
- [配置](#-配置)
- [支持的服务器类型](#-支持的服务器类型)
- [示例](#-示例)
- [架构](#-架构)
- [贡献](#-贡献)
- [许可证](#-许可证)
## 🚀 安装
### 先决条件
- Python 3.10 或更高版本
- Docker 或 Podman（用于基于容器的 MCP 服务器）
- Node.js（用于基于 npm 的 MCP 服务器）
- Claude Code CLI
### 使用 uv 安装（推荐）
```bash
uv tool install mcp-ctrl
mcpctl list
```
### 使用 pip 安装
```bash
pip install mcp-ctrl
mcpctl list
```
### 从源代码安装
```bash
git clone https://github.com/savitojs/mcpctl.git
cd mcpctl
uv sync
uv run mcpctl list
```
> **注意：** PyPI 包名为 `mcp-ctrl`，但命令为 `mcpctl`
> **提示：** 管理 Python 环境？ [setV](https://github.com/savitojs/setV) 将它们放在一个地方，提供 uv 支持的创建、自动冻结和 `setv doctor` 以修复 OS 升级后的损坏环境。
## ⚡ 快速入门
### 1. 配置环境变量
mcpctl 首先从您的 shell 环境中解析 `${VAR}` 引用，然后回退到 `.env` 文件。 在您喜欢的位置设置它们：
```bash
# 选项 A：shell 配置文件（~/.zshenv、~/.bashrc、~/.profile 等）
export GITHUB_PAT=ghp_your_github_token_here
export EXA_API_KEY=your_exa_api_key
# 选项 B：dotenv 文件（~/.env）
GITHUB_PAT=ghp_your_github_token_here
EXA_API_KEY=your_exa_api_key
```
### 2. 列出可用服务器
```bash
mcpctl list
```
输出：
```
可用 MCP 服务器：
⚪ 禁用 | 文件系统 | npm | 安全文件操作
⚪ 禁用 | GitHub | npm | GitHub 仓库管理
⚪ 禁用 | 顺序思考 | npm | 结构化推理
🐳 ⚪ 禁用 | PostgreSQL | docker | PostgreSQL 数据库访问
... (13 个服务器可用于示例)
```
### 3. 启用服务器
```bash
# 启用基于 npm 的服务器
mcpctl enable filesystem
# 启用基于 docker 的服务器（自动启动容器）
mcpctl enable postgres
```
### 4. 检查详细信息
```bash
mcpctl list filesystem
```
### 5. 禁用时
```bash
mcpctl disable filesystem
```
## 📖 用法
### 命令
| 命令 | 描述 | 示例 |
|---------|-------------|---------|
| `list` | 列出所有服务器，或显示一个服务器的详细信息 | `mcpctl list` / `mcpctl list github` |
| `config` | 显示当前配置和路径 | `mcpctl config` |
| `enable <server>` | 启用服务器（s），如果需要，启动容器 | `mcpctl enable github filesystem` |
| `disable <server>` | 禁用服务器（s）并停止容器 | `mcpctl disable postgres` |
### 选项
```bash
# 在全局配置中启用（~/.claude.json）
mcpctl enable --global github
# 在项目配置中启用（.mcp.json）
mcpctl enable --project github
# 预览更改而不应用
mcpctl enable --dry-run github
# 禁用服务器但保持容器运行
mcpctl disable postgres --keep-container
# 获取帮助
mcpctl --help
mcpctl <command> --help
```
## ⚙️ 配置
mcpctl 将配置存储在 `~/.config/mcpctl/` 中：
- `mcp-servers.yaml` - 您的 MCP 服务器配置
### 配置文件
`mcp-servers.yaml` 定义了所有可用的 MCP 服务器。 有关完整示例，请参见 [examples/mcp-servers.example.yaml](examples/mcp-servers.example.yaml)。
### 环境变量
在 YAML 中使用 `${VAR_NAME}` 语法进行环境变量替换：
```yaml
env:
GITHUB_TOKEN: "${GITHUB_TOKEN}"
```
变量解析自（最后一个获胜）：
1. `~/.env`
2. `.env`（项目本地覆盖）
3. Shell 环境（`~/.zshenv`、`~/.bashrc`、`~/.profile`等）
### 添加新的 MCP 服务器
编辑 `mcp-servers.yaml`：
```yaml
servers:
my-server:
type: npm # 或 docker、python、executable
description: "此服务器的作用"
transport: stdio
requires_container: false
mcp_config:
command: npx
args:
- -y
- "@org/my-mcp-server"
env: {}
```
## 🎯 支持的服务器类型
### 1. npm 包（npx）
```yaml
filesystem:
type: npm
requires_container: false
mcp_config:
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- /path/to/dir
```
### 2. Python 包（uvx）
```yaml
python-server:
type: python
requires_container: false
mcp_config:
command: uvx
args:
- python-mcp-package
```
### 3. Docker 容器
```yaml
postgres:
type: docker
requires_container: true
container:
name: mcp-postgres
image: postgres:16-alpine
ports:
- "5432:5432"
environment:
POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
POSTGRES_DB: mydb
mcp_config:
command: npx
args:
- -y
- mcp-postgres
- postgresql://postgres:${POSTGRES_PASSWORD}@localhost:5432/mydb
```
### 4. 自定义可执行文件
```yaml
custom-server:
type: executable
requires_container: false
mcp_config:
command: /path/to/mcp-server
args:
- --config
- /path/to/config.json
```
## 💡 示例
### 启用 PostgreSQL（带有 Docker 容器）
```bash
$ mcpctl enable postgres
ℹ️ 启动容器：docker run -d --name mcp-postgres -p 5432:5432 ...
✅ 容器 'mcp-postgres' 已启动
✅ 服务器 'postgres' 已在 Claude 配置中启用
⚠️ 重启 Claude Code 以应用更改
```
### 启用 GitHub（npm 包）
```bash
$ mcpctl enable github
✅ 服务器 'github' 已在 Claude 配置中启用
⚠️ 重启 Claude Code 以应用更改
```
### 检查服务器详细信息
```bash
$ mcpctl list github
github
类型： 远程
描述： GitHub 仓库管理（官方远程服务器）
传输： http
范围： 全局
环境变量： GITHUB_PAT
```
### 显示配置
```bash
$ mcpctl config
mcpctl 配置
配置文件： ~/.config/mcpctl/mcp-servers.yaml
默认范围： 全局
容器： /usr/bin/podman
定义的服务器：6
filesystem
github
memory
...
```
## 🏗️ 架构
```mermaid
flowchart TB
subgraph mcpctl["mcpctl"]
CLI["CLI（enable / disable / list / config）"]
end
YAML["~/.config/mcpctl/<br/>mcp-servers.yaml"]
ENV["环境<br/>shell 环境 / .env 文件"]
subgraph targets["Claude 配置"]
GLOBAL["~/.claude.json<br/>(全局)"]
PROJECT[".mcp.json<br/>(项目)"]
end
subgraph containers["容器运行时"]
PODMAN["Podman / Docker"]
end
YAML -->|读取服务器<br/>定义| CLI
ENV -->|解析<br/>环境变量机密| CLI
CLI -->|写入 mcpServers| GLOBAL
CLI -->|写入 mcpServers| PROJECT
CLI -->|启动 / 停止| PODMAN
style mcpctl fill:#1e1b4b,stroke:#8b5cf6,color:#e2e8f0
style CLI fill:#2e1065,stroke:#8b5cf6,color:#e2e8f0
style YAML fill:#1e293b,stroke:#334155,color:#94a3b8
style ENV fill:#1e293b,stroke:#334155,color:#94a3b8
style GLOBAL fill:#14532d,stroke:#22c55e,color:#bbf7d0
style PROJECT fill:#14532d,stroke:#22c55e,color:#bbf7d0
style PODMAN fill:#172554,stroke:#3b82f6,color:#bfdbfe
style targets fill:#0a1a0a,stroke:#22c55e,color:#86efac
style containers fill:#0a1528,stroke:#3b82f6,color:#93c5fd
```
### 工作原理
**容器服务器（Docker/Podman）：**
`enable` 启动容器 + 写入 Claude 配置。`disable` 停止它 + 删除条目。
**包服务器（npm/Python）：**
`enable` 写入 Claude 配置（包在 Claude 需要时自动运行）。`disable` 删除条目。
## 🛠️ 故障排除
### 容器无法启动
```bash
# 检查 Docker/Podman 是否正在运行
docker ps # 或：podman ps
# 检查容器日志
docker logs <container-name>
# 手动启动容器
docker start <container-name>
# 或使用 podman：
podman start <container-name>
# 然后在 Claude 配置中启用
mcpctl enable <server-name>
```
### 环境变量不起作用
```bash
# 验证 .env 文件
cat ~/.env
# 检查替换
mcpctl list github
```
### MCP 未出现在 Claude Code 中
```bash
# 验证已添加配置
cat ~/.claude.json | grep <server-name>
# 重启 Claude Code
# （退出并重启 CLI）
```
## 📚 预配置服务器
mcpctl 包含流行的 MCP 服务器的示例配置。有关 13+ 预配置服务器示例，请参阅 `~/.config/mcpctl/mcp-servers-examples.yaml` 文件或存储库中的 `examples/` 目录：
- 文件操作（filesystem）
- GitHub 集成
- 浏览器自动化（playwright、puppeteer）
- 数据库访问（postgres）
- 网络搜索（brave-search）
- 知识图谱（memory）
- HTTP 请求（fetch）
- 以及更多...
## 🤝 贡献
欢迎贡献！请：
1. 复刻仓库
2. 创建一个功能分支（`git checkout -b feature/amazing-feature`）
3. 提交您的更改（`git commit -m 'Add amazing feature'`）
4. 推送到分支（`git push origin feature/amazing-feature`）
5. 打开拉取请求
### 添加新的服务器配置
要贡献新的 MCP 服务器配置：
1. 将服务器定义添加到 `examples/mcp-servers.example.yaml`
2. 使用 `mcpctl enable your-server` 进行测试
3. 记录所需的环境变量
4. 提交 PR 及服务器详细信息
## 📝 许可证
该项目使用 MIT 许可证 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## 🙏 致谢
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 规范
- [Claude Code](https://code.claude.com/) - AI 驱动的编码助手
- [Anthropic](https://www.anthropic.com/) - Claude AI
## 📧 支持
- 📖 [文档](docs/)
- 🐛 [问题跟踪器](https://github.com/savitojs/mcpctl/issues)
- 💬 [讨论](https://github.com/savitojs/mcpctl/discussions)
---
**由 Claude Code 社区 ❤️ 制作**
