功能强大的模型上下文协议(MCP)命令行界面工具
NOASSERTIONPython 1.4kchrishayukmcp-cli Last Updated: 2025-07-02
MCP-CLI:模型上下文协议命令行界面工具
项目概述
MCP-CLI是一个功能强大、特性丰富的命令行界面工具,专门用于与模型上下文协议(Model Context Protocol,MCP)服务器交互。该工具通过集成CHUK-MCP协议库,为用户提供了与大语言模型(LLM)的无缝通信能力。
该客户端支持工具使用、对话管理和多种操作模式,核心协议实现已迁移到独立的包中,使得CLI专注于提供丰富的用户体验,而协议库负责处理通信层。
核心特性
🔄 多种操作模式
- 聊天模式(Chat Mode):对话式界面,支持直接LLM交互和自动化工具使用
- 交互模式(Interactive Mode):命令驱动界面,用于直接服务器操作
- 命令模式(Command Mode):Unix友好模式,支持脚本化自动化和管道操作
- 直接命令:无需进入交互模式即可运行单个命令
🌐 多提供商支持
- OpenAI集成:支持
gpt-4o-mini
、gpt-4o
、gpt-4-turbo
等模型 - Ollama集成:支持
llama3.2
、qwen2.5-coder
等本地模型 - 可扩展架构:支持添加其他提供商
🛠️ 强大的工具系统
- 自动发现服务器提供的工具
- 服务器感知的工具执行
- 工具调用历史跟踪和分析
- 支持复杂的多步骤工具链
💬 高级对话管理
- 完整的对话历史跟踪
- 支持过滤和查看特定消息范围
- JSON导出功能,用于调试或分析
- 对话压缩功能,减少token使用
🎨 丰富的用户体验
- 上下文感知的命令自动完成
- 彩色格式化的控制台输出
- 长时间运行操作的进度指示器
- 详细的帮助和文档
🔧 可靠的资源管理
- 适当的异步IO资源清理
- 优雅的错误处理
- 干净的终端恢复
- 支持多个同时服务器连接
系统要求
- Python 3.11或更高版本
- 对于OpenAI:需要在
OPENAI_API_KEY
环境变量中设置有效的API密钥 - 对于Ollama:需要本地Ollama安装
- 服务器配置文件(默认:
server_config.json
) - CHUK-MCP协议库
安装方法
标准安装
# 克隆仓库
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
# 安装包和开发依赖
pip install -e ".[cli,dev]"
# 运行CLI
mcp-cli --help
使用UV管理依赖
# 安装UV(如果未安装)
pip install uv
# 安装依赖
uv sync --reinstall
# 使用UV运行
uv run mcp-cli --help
使用指南
全局选项
所有命令都支持以下全局选项:
--server
:指定要连接的服务器(多个服务器用逗号分隔)--config-file
:服务器配置文件路径(默认:server_config.json
)--provider
:使用的LLM提供商(openai
或ollama
,默认:openai
)--model
:使用的特定模型(依赖于提供商的默认值)--disable-filesystem
:禁用文件系统访问(默认:true)
聊天模式
聊天模式提供与LLM的对话界面,在需要时自动使用可用工具:
# 基础聊天模式
mcp-cli chat --server sqlite
# 指定提供商和模型
mcp-cli chat --server sqlite --provider openai --model gpt-4o
mcp-cli chat --server sqlite --provider ollama --model llama3.2
聊天模式斜杠命令
在聊天模式中,可以使用以下斜杠命令:
帮助命令:
/help
:显示可用命令/help <command>
:显示特定命令的详细帮助/quickhelp
或/qh
:显示常用命令的快速参考
工具相关:
/tools
:显示所有可用工具及其服务器信息/tools --all
:显示包含参数的详细工具信息/tools --raw
:显示原始工具定义/toolhistory
或/th
:显示当前会话中的工具调用历史
对话管理:
/conversation
或/ch
:显示对话历史/save <filename>
:将对话历史保存到JSON文件/compact
:将对话历史压缩为摘要
界面控制:
/cls
:清除屏幕但保留对话历史/clear
:清除屏幕和对话历史/verbose
或/v
:切换详细和简洁工具显示模式
交互模式
交互模式提供命令行界面,使用斜杠命令进行直接服务器交互:
mcp-cli interactive --server sqlite
交互模式命令
/ping
:检查服务器是否响应/prompts
:列出可用提示/tools
:列出可用工具/resources
:列出可用资源/chat
:进入聊天模式/exit
或/quit
:退出程序
命令模式
命令模式提供Unix友好的接口,用于自动化和管道集成:
mcp-cli cmd --server sqlite [options]
命令模式选项
--input
:输入文件路径(使用-
表示stdin)--output
:输出文件路径(使用-
表示stdout,默认)--prompt
:提示模板(使用{{input}}
作为输入占位符)--raw
:输出原始文本而不格式化--tool
:直接调用特定工具--tool-args
:工具调用的JSON参数--system-prompt
:自定义系统提示
命令模式示例
# 总结文档
mcp-cli cmd --server sqlite --input document.md --prompt "Summarize this: {{input}}" --output summary.md
# 处理stdin并输出到stdout
cat document.md | mcp-cli cmd --server sqlite --input - --prompt "Extract key points: {{input}}"
# 直接调用工具
mcp-cli cmd --server sqlite --tool list_tables --raw
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'
# 批量处理
ls *.md | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary.md --prompt "Summarize: {{input}}"
直接命令
无需进入交互模式即可运行单个命令:
# 列出可用工具
mcp-cli tools list --server sqlite
# 调用特定工具
mcp-cli tools call --server sqlite
# 列出可用提示
mcp-cli prompts list --server sqlite
# 检查服务器连接
mcp-cli ping --server sqlite
# 列出可用资源
mcp-cli resources list --server sqlite
配置文件
创建server_config.json
文件配置服务器:
{
"mcpServers": {
"sqlite": {
"command": "python",
"args": ["-m", "mcp_server.sqlite_server"],
"env": {
"DATABASE_PATH": "your_database.db"
}
},
"another-server": {
"command": "python",
"args": ["-m", "another_server_module"],
"env": {}
}
}
}
项目结构
src/
├── mcp_cli/
│ ├── chat/ # 聊天模式实现
│ │ ├── commands/ # 聊天斜杠命令
│ │ │ ├── __init__.py # 命令注册系统
│ │ │ ├── conversation.py # 对话管理
│ │ │ ├── help.py # 帮助命令
│ │ │ ├── tools.py # 工具命令
│ │ │ └── ...
│ │ ├── chat_context.py # 聊天会话状态管理
│ │ ├── chat_handler.py # 主聊天循环处理器
│ │ ├── command_completer.py # 命令自动完成
│ │ └── ui_manager.py # 用户界面
│ ├── commands/ # CLI命令
│ │ ├── chat.py # 聊天命令
│ │ ├── cmd.py # 命令模式
│ │ ├── interactive.py # 交互模式
│ │ └── ...
│ ├── llm/ # LLM客户端实现
│ │ ├── providers/ # 提供商特定客户端
│ │ │ ├── base.py # 基础LLM客户端
│ │ │ └── openai_client.py # OpenAI实现
│ │ └── llm_client.py # 客户端工厂
│ ├── ui/ # 用户界面组件
│ │ ├── colors.py # 颜色定义
│ │ └── ui_helpers.py # UI工具
│ ├── main.py # 主入口点
│ └── config.py # 配置加载器
使用示例
自动工具执行
在聊天模式中,MCP CLI可以自动执行服务器提供的工具:
You: What tables are available in the database?
Assistant: Let me check for you.
[Tool Call: list_tables]
I found the following tables in the database:
- users
- products
- orders
- categories
You: How many users do we have?
Assistant: I'll query the database for that information.
[Tool Call: read_query]
There are 873 users in the database.
自动化脚本
命令模式支持强大的自动化脚本:
#!/bin/bash
# 分析多个文档的示例脚本
# 处理当前目录中的所有markdown文件
for file in *.md; do
echo "Processing $file..."
# 生成摘要
mcp-cli cmd --server sqlite --input "$file" \
--prompt "Summarize this document: {{input}}" \
--output "${file%.md}.summary.md"
# 提取实体
mcp-cli cmd --server sqlite --input "$file" \
--prompt "Extract all company names, people, and locations from this text: {{input}}" \
--output "${file%.md}.entities.txt" --raw
done
# 创建综合报告
echo "Creating final report..."
cat *.entities.txt | mcp-cli cmd --server sqlite --input - \
--prompt "Analyze these entities and identify the most frequently mentioned:" \
--output report.md
对话历史管理
跟踪和管理对话历史:
> /conversation
Conversation History (12 messages)
# | Role | Content
1 | system | You are an intelligent assistant capable of using t...
2 | user | What tables are available in the database?
3 | assistant | Let me check for you.
4 | assistant | [Tool call: list_tables]
...
> /conversation 4
Message #4 (Role: assistant)
[Tool call: list_tables]
Tool Calls:
1. ID: call_list_tables_12345678, Type: function, Name: list_tables
Arguments: {}
> /save conversation.json
Conversation saved to conversation.json
> /compact
Conversation history compacted with summary.
Summary:
The user asked about database tables, and I listed the available tables (users, products, orders, categories). The user then asked about the number of users, and I queried the database to find there are 873 users.
依赖管理
CLI使用可选的依赖组进行组织:
- cli:丰富的终端UI、命令自动完成和提供商集成
- dev:开发工具和测试工具
- wasm:(为未来WebAssembly支持保留)
- chuk-mcp:协议实现库(核心依赖)
安装特定extras:
pip install "mcp-cli[cli]" # 基础CLI功能
pip install "mcp-cli[cli,dev]" # CLI + 开发工具
贡献指南
欢迎贡献!请遵循以下步骤:
- Fork仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature
) - 提交更改 (
git commit -m 'Add some amazing feature'
) - 推送到分支 (
git push origin feature/amazing-feature
) - 打开Pull Request
关于模型上下文协议(MCP)
MCP是一个开放协议,标准化了应用程序为LLM提供上下文的方式。可以将MCP比作AI应用程序的USB-C端口。正如USB-C为连接设备到各种外围设备和配件提供了标准化方式,MCP为连接AI模型到各种数据源和工具提供了标准化方式。