MCP CLI - 模型上下文协议命令行界面

一个功能强大、特性丰富的命令行界面，用于与模型上下文协议服务器交互。该客户端通过与CHUK工具处理器和CHUK-LLM集成，实现与大语言模型的无缝通信，提供工具使用、对话管理以及多种操作模式。

默认配置：MCP CLI 默认使用 Ollama，并采用 gpt-oss 推理模型，以实现本地、注重隐私的操作，无需 API 密钥。

🆕 最近更新（v0.16）

AI 虚拟内存（实验性）

• --vm 标志：启用操作系统风格的虚拟内存，用于对话上下文管理，由 chuk-ai-session-manager 提供支持
• --vm-budget：控制对话事件的标记预算（系统提示不受限制），强制较早驱逐并创建页面
• --vm-mode：选择 VM 模式——passive（运行时管理，默认）、relaxed（感知 VM 的对话）或 strict（模型驱动的分页与工具结合）
• /memory 命令：可视化对话期间的 VM 状态——页表、工作集利用率、驱逐指标、TLB 统计信息（别名：/vm、/mem）
• 多模态 page_fault：图像页面返回多块内容（文本 + image_url），以便多模态模型可重新分析召回的图像
• /memory page <id> --download：将页面内容导出到本地文件，并带有模态感知的扩展名（.txt、.json、.png）

执行计划（第 6 层）

• /plan 命令：创建、检查和执行可复现的工具调用图——create、list、show、run、delete、resume
• 模型驱动规划 (--plan-tools)：大语言模型在对话过程中自主创建并执行计划——无需 /plan 命令。当需要多步骤编排时调用 plan_create_and_execute，简单任务则使用常规工具。每一步都在终端中实时显示进度
• 并行批量执行：独立的计划步骤通过拓扑排序批量执行（Kahn 的 BFS），可配置 max_concurrency
• 变量解析：${var}、${var.field} 嵌套访问，以及类似 "https://${api.host}/users" 的模板字符串——对单个引用保持类型一致
• 干运行模式：跟踪计划的工具调用而不实际执行——适合生产环境检查
• 检查点与恢复：每次批量后持久化执行状态；中断的计划可通过 /plan resume <id> 恢复
• 防护集成：计划尊重现有预算、每工具限制及失控检测防护
• DAG 可视化：ASCII 渲染，带状态指示符（○/◉/●/✗）和并行标记符（∥）
• 重新规划：可选的基于大语言模型的重新规划，在步骤失败时启用 (enable_replan=True)
• 驱动技术：chuk-ai-planner 图形化计划 DSL

MCP 应用程序（SEP-1865）

• 交互式 HTML UI：MCP 服务器可提供交互式 HTML 应用程序（图表、表格、地图、Markdown 查看器），在浏览器中渲染
• 沙箱 iframe：应用运行于安全的沙箱 iframe 中，具备 CSP 防护
• WebSocket 桥接：浏览器应用与 MCP 服务器之间的实时双向通信
• 自动启动：带有 _meta.ui 注解的工具在调用时会自动在浏览器中打开
• 会话可靠性：消息队列、指数退避重连、延迟工具结果交付

生产环境加固

• 密钥脱敏：所有日志输出（控制台和文件）都会自动脱敏 Bearer 令牌、API 密钥、OAuth 令牌和授权头
• 结构化文件日志：可选的 --log-file 标志启用轮转 JSON 日志文件（10MB，3 个备份），级别为 DEBUG
• 每服务器超时：服务器配置支持 tool_timeout 和 init_timeout 覆盖，按服务器 → 全局 → 默认解析
• 线程安全 OAuth：并发 OAuth 流程通过 asyncio.Lock 序列化，且头部变更采用写时复制
• 服务器健康监测：/health 命令、故障时健康检查诊断，可选的 --health-interval 后台轮询

性能与优化

• O(1) 工具查找：索引化的工具查找取代了 O(n) 的线性扫描
• 缓存 LLM 工具元数据：按提供商缓存，自动失效
• 启动进度：初始化期间的实时进度消息
• 标记使用追踪：每轮及累计追踪，通过 /usage 命令（别名：/tokens、/cost）
• 会话持久化：保存/加载/列出对话会话，每 10 轮自动保存（/sessions）
• 对话导出：将对话导出为 Markdown 或 JSON 并附带元数据（/export）

仪表板（实时浏览器 UI）

• --dashboard 标志：在聊天模式旁启动实时浏览器仪表板
• 代理终端：实时对话视图，带消息气泡、流式标记和附件渲染
• 活动流：工具调用/结果对、推理步骤及用户附件事件
• 计划查看器：可视化执行计划进度，带 DAG 渲染
• 工具注册表：浏览发现的工具，从浏览器触发执行
• 配置面板：查看并切换提供商、模型及系统提示
• 文件附件：浏览器文件上传的“+”按钮，拖放及剪贴板粘贴支持

多模态附件

• /attach 命令：为下一条消息暂存文件——图片、文本/代码及音频（别名：/file、/image）
• --attach CLI 标志：为第一条消息附加文件（可重复：--attach img.png --attach code.py）
• 内联 @file: 引用：在消息任意位置提及 @file:路径/文件 即可附加
• 图片 URL 检测：消息中的 HTTP/HTTPS 图片 URL 会自动作为视觉内容发送
• 支持格式：PNG、JPEG、GIF、WebP、HEIC（图片）、MP3、WAV（音频），以及 25+ 文本/代码扩展
• 仪表板渲染：图片缩略图、可展开的文本预览、音频播放器、文件标签
• 浏览器上传：仪表板聊天输入中的“+”按钮，支持拖放及剪贴板粘贴

代码质量

• 核心与 UI 分离：核心模块仅使用 logging——不引入 UI
• 4,300+ 测试：全面测试套件，包含分支覆盖率、集成测试及 60% 的最低阈值
• 15 项架构原则：已文档化并强制执行（参见 architecture.md）
• 完整路线图：第 1-6 层已完成，第 7-12 层规划中（追踪、内存范围、技能、调度、多智能体）

🔄 架构概览

MCP CLI 基于模块化架构构建，实现了清晰的职责分离：

• CHUK 工具处理器：生产级异步工具执行，内置中间件（重试、熔断器、限流）、多种执行策略及可观测性功能。
• CHUK-LLM：统一的大型语言模型提供商，支持动态模型发现、基于能力的选择以及 llama.cpp 集成（比 Ollama 快 1.53 倍，并自动复用模型）。
• CHUK-Term：增强型终端 UI，支持主题切换、跨平台终端管理及丰富的格式化功能。
• MCP CLI：命令编排与集成层（本项目）。

🌟 主要特性

多种运行模式

• 聊天模式：对话式界面，支持流式响应和自动化工具使用（默认：Ollama/gpt-oss）。
• 交互模式：命令驱动的 Shell 界面，用于直接操作服务器。
• 命令模式：兼容 Unix 的模式，适合脚本化自动化与流水线。
• 直接命令：无需进入交互模式即可直接运行单个命令。

先进的聊天界面

• 流式响应：实时生成响应并同步更新 UI。
• 推理可见性：通过推理模型（gpt-oss、GPT-5、Claude 4.5）查看 AI 的思考过程。
• 并发工具执行：同时执行多个工具，同时保持对话顺序。
• 智能中断：按 Ctrl+C 可中断流式响应或工具执行。
• 性能指标：包括响应时间、每秒词数及执行统计信息。
• 丰富格式化：支持 Markdown 渲染、语法高亮及进度指示器。
• Token 使用追踪：通过 /usage 命令可查看每轮及累计的 API Token 使用情况。
• 多模态附件：可通过 /attach、--attach、@file: 引用或浏览器上传方式，向消息中添加图片、文本文件及音频。
• 会话持久化：自动保存及手动保存/加载对话会话。
• 对话导出：支持以 Markdown 或 JSON 格式导出对话内容，包含元数据及 Token 使用信息。

全面的提供商支持

MCP CLI 支持 CHUK-LLM 的所有提供商与模型，包括前沿推理模型：

提供商	关键模型	特殊功能
Ollama（默认）	🧠 gpt-oss、llama3.3、llama3.2、qwen3、qwen2.5-coder、deepseek-coder、granite3.3、mistral、gemma3、phi3、codellama	本地推理模型，注重隐私，无需 API 密钥
OpenAI	🚀 GPT-5 系列（gpt-5、gpt-5-mini、gpt-5-nano）、GPT-4o 系列、O3 系列（o3、o3-mini）	高级推理、函数调用、视觉处理
Anthropic	🧠 Claude 4.5 系列（claude-4-5-opus、claude-4-5-sonnet）、Claude 3.5 Sonnet	增强推理能力，长上下文支持
Azure OpenAI 🏢	企业版 GPT-5、GPT-4 模型	私有端点、合规性、审计日志
Google Gemini	Gemini 2.0 Flash、Gemini 1.5 Pro	多模态，快速推理
Groq ⚡	Llama 3.1 模型、Mixtral	超高速推理（500+ tokens/sec）
Perplexity 🌐	Sonar 模型	实时网络搜索并附带引用
IBM watsonx 🏢	Granite、Llama 模型	企业级合规性
Mistral AI 🇪🇺	Mistral Large、Medium	欧洲高效模型

强大的工具系统（由 CHUK 工具处理器 v0.22+ 提供支持）

• 自动发现：服务器提供的工具会自动检测并编入目录。
• 提供商适配：工具名称会自动清理以适应不同提供商。
• 生产级执行：内置中间件层，支持超时、重试、指数退避、缓存及熔断机制。
• 多种执行策略：进程内（快速）、独立子进程（安全），或通过 MCP 远程执行。
• 并发执行：多个工具可同时运行并协调一致。
• 丰富的进度显示：实时进度指示器及执行计时。
• 工具历史：完整记录所有工具执行的审计轨迹。
• 中间件：通过 CTP 支持指数退避重试、熔断器及限流。
• 流式工具调用：支持返回流式数据的工具。

MCP 应用程序（交互式 UI）

• 基于浏览器的 UI：MCP 服务器可提供交互式 HTML 应用程序，在浏览器中渲染。
• 自动检测：带有 _meta.ui 注解的工具会在调用时自动启动浏览器应用。
• 沙箱执行：应用运行在受保护的沙箱 iframe 中，具备内容安全策略防护。
• WebSocket 桥接：浏览器应用与 MCP 工具服务器之间的实时 JSON-RPC 桥接。
• 会话持久化：断开连接时的消息队列、自动重连及延迟工具结果交付。
• structuredContent 支持：完全符合 MCP 规范，包括结构化内容提取与转发。

执行计划（由 chuk-ai-planner 提供支持）

• 计划创建：通过自然语言描述生成执行计划，使用基于 LLM 的计划代理。
• 模型驱动规划：使用 --plan-tools 参数，LLM 自主决定何时规划——对复杂多步骤任务调用 plan_create_and_execute，简单任务则直接使用常规工具。
• DAG 执行：计划为有向无环图——独立步骤并行批次执行，依赖步骤等待。
• 变量解析：步骤输出绑定到变量（result_variable），后续步骤可引用为 ${var} 或 ${var.field}。
• 干运行模式：在不执行任何工具的情况下跟踪计划将如何执行——适用于生产环境的安全测试。
• 检查点：每次批次后保存执行状态；恢复中断的计划，无需重新执行已完成步骤。
• Guard 集成：计划与对话共享预算及每工具限制——不可绕过。
• 重新规划：当步骤失败时，可选择调用 LLM 生成剩余工作的修订计划。
• DAG 可视化：ASCII 渲染展示依赖关系结构、批次分组及并行标记。
• 持久化：计划以 JSON 格式存储在 ~/.mcp-cli/plans/。

高级配置管理

• 环境集成：通过环境变量管理 API 密钥与设置。
• 文件配置：支持 YAML 和 JSON 配置文件。
• 用户偏好：保存活跃提供商与模型的持久化设置。
• 验证与诊断：内置提供商健康检查与配置验证。

优化的用户体验

• 跨平台支持：Windows、macOS 和 Linux，通过 chuk-term 实现针对各平台的优化
• 丰富的控制台输出：由 chuk-term 提供支持，内置 8 种主题（默认、深色、浅色、极简、终端、Monokai、Dracula、Solarized）
• 高级终端管理：跨平台终端操作功能，包括清除、调整大小、颜色检测和光标控制
• 交互式 UI 组件：通过 chuk-term 的提示系统处理用户输入（ask、confirm、select_from_list、select_multiple）
• 命令补全：所有界面均支持上下文感知的 Tab 键补全
• 全面的帮助文档：提供详尽的帮助系统，包含示例和使用模式
• 友好的错误处理：提供用户友好的错误信息，并附带故障排除提示

📚 文档

完整的文档位于 docs/ 目录中：

项目

• 架构 - 15 项设计原则、模块布局和编码规范
• 路线图 - 愿景、已完成的阶段（1-5）、以及计划中的阶段（6-12：规划、追踪、技能、调度、多智能体、远程会话）

核心文档

• 命令系统 - 统一命令系统的完整指南、模式及所有模式下的用法
• 令牌管理 - 针对提供商和服务器的全面令牌管理，包括 OAuth、Bearer 令牌和 API 密钥

专项文档

• 执行计划 - 计划创建、并行执行、变量解析、检查点、守卫和重新规划
• 仪表板 - 实时浏览器 UI，包含智能体终端、活动流和文件上传
• 附件 - 多模态文件附件：图片、文本、音频和浏览器上传
• MCP 应用 - 由 MCP 服务器提供的交互式浏览器 UI（SEP-1865）
• OAuth 认证 - OAuth 流程、存储后端和 MCP 服务器集成
• 流式集成 - 实时响应流式架构
• 包管理 - 依赖组织和功能分组

UI 文档

• 主题 - 主题系统和自定义
• 输出系统 - 丰富的控制台输出和格式化
• 终端管理 - 跨平台终端操作

测试文档

• 单元测试 - 测试结构和模式
• 测试覆盖率 - 覆盖率要求和报告

📋 先决条件

• Python 3.11 或更高版本
• 本地运行（默认）：
  • Ollama：从 ollama.ai 安装
  • 拉取默认推理模型：ollama pull gpt-oss
• 云端提供商（可选）：
  • OpenAI：OPENAI_API_KEY 环境变量（用于 GPT-5、GPT-4、O3 模型）
  • Anthropic：ANTHROPIC_API_KEY 环境变量（用于 Claude 4.5、Claude 3.5）
  • Azure：AZURE_OPENAI_API_KEY 和 AZURE_OPENAI_ENDPOINT（用于企业版 GPT-5）
  • Google：GEMINI_API_KEY（用于 Gemini 模型）
  • Groq：GROQ_API_KEY（用于快速 Llama 模型）
  • 自定义提供商：特定提供商的配置
• MCP 服务器：服务器配置文件（默认：server_config.json）

🚀 安装

使用 Ollama 快速入门（默认）

1. 安装 Ollama（如果尚未安装）：

# macOS/Linux
curl -fsSL https://ollama.ai/install.sh | sh

# 或访问 https://ollama.ai 获取其他安装方法

2. 拉取默认推理模型：

ollama pull gpt-oss  # 开源推理模型，具备思考可视化功能

3. 安装并运行 MCP CLI：

# 推荐使用 uvx
uvx mcp-cli --help

# 或从源码安装
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
pip install -e "."
mcp-cli --help

# 可选：启用 MCP 应用（交互式浏览器 UI）
pip install -e ".[apps]"

使用不同模型

# === 本地模型（无需 API 密钥）===

# 使用默认推理模型（gpt-oss）
mcp-cli --server sqlite

# 使用其他 Ollama 模型
mcp-cli --model llama3.3              # 最新 Llama
mcp-cli --model qwen2.5-coder         # 专注编码
mcp-cli --model deepseek-coder        # 另一种编码模型
mcp-cli --model granite3.3            # IBM Granite

# === 云端提供商（需要 API 密钥）===

# GPT-5 系列（需 OpenAI API 密钥）
mcp-cli --provider openai --model gpt-5          # 全功能 GPT-5，具备推理能力
mcp-cli --provider openai --model gpt-5-mini     # 高效 GPT-5 变体
mcp-cli --provider openai --model gpt-5-nano     # 超轻量级 GPT-5

# GPT-4 系列
mcp-cli --provider openai --model gpt-4o         # GPT-4 优化版
mcp-cli --provider openai --model gpt-4o-mini    # 较小的 GPT-4

# O3 推理模型
mcp-cli --provider openai --model o3             # O3 推理
mcp-cli --provider openai --model o3-mini        # 高效 O3

# Claude 4.5 系列（需 Anthropic API 密钥）
mcp-cli --provider anthropic --model claude-4-5-opus    # 最先进的 Claude
mcp-cli --provider anthropic --model claude-4-5-sonnet  # 平衡的 Claude 4.5
mcp-cli --provider anthropic --model claude-3-5-sonnet  # Claude 3.5

# 企业版 Azure（需 Azure 配置）
mcp-cli --provider azure_openai --model gpt-5    # 企业版 GPT-5

# 其他提供商
mcp-cli --provider gemini --model gemini-2.0-flash      # Google Gemini
mcp-cli --provider groq --model llama-3.1-70b          # 通过 Groq 的快速 Llama

🧰 全局配置

默认配置

MCP CLI 默认设置为：

• 提供商：ollama（本地，无需 API 密钥）
• 模型：gpt-oss（开源推理模型，具备思考可视化功能）

命令行参数

适用于所有模式和命令的全局选项：

• --server：指定要连接的服务器（以逗号分隔）
• --config-file：服务器配置文件的路径（默认：server_config.json）
• --provider：LLM 提供商（默认：ollama）
• --model：要使用的特定模型（默认：对于 Ollama 为 gpt-oss）
• --disable-filesystem：禁用文件系统访问（默认：启用）
• --api-base：覆盖 API 端点 URL
• --api-key：覆盖 API 密钥（对于 Ollama 不需要）
• --token-backend：覆盖令牌存储后端（auto、keychain、windows、secretservice、encrypted、vault）
• --verbose：启用详细日志记录
• --quiet：抑制非必要输出
• --log-file：将调试日志写入轮转文件（自动脱敏密钥）
• --vm：[实验性] 启用 AI 虚拟内存进行上下文管理
• --vm-budget：VM 模式下对话事件的令牌预算（默认：128000，位于系统提示之上）
• --vm-mode：VM 模式——passive（默认）、relaxed 或 strict
• --dashboard：在聊天模式旁启动实时浏览器仪表板 UI
• --attach：将文件附加到第一条消息（可重复：--attach img.png --attach code.py）
• --plan-tools：启用模型驱动规划——LLM 自主创建并执行多步骤计划
• --no-tools：完全禁用 MCP 工具调用——直接与 LLM 对话，无需连接任何 MCP 服务器

环境变量

# 覆盖默认值
export LLM_PROVIDER=ollama              # 默认提供商（已为默认值）
export LLM_MODEL=gpt-oss                # 默认模型（已为默认值）

# 对于云提供商（可选）
export OPENAI_API_KEY=sk-...           # 对于 GPT-5、GPT-4、O3 模型
export ANTHROPIC_API_KEY=sk-ant-...    # 对于 Claude 4.5、Claude 3.5
export AZURE_OPENAI_API_KEY=sk-...     # 对于企业版 GPT-5
export AZURE_OPENAI_ENDPOINT=https://...
export GEMINI_API_KEY=...              # 对于 Gemini 模型
export GROQ_API_KEY=...                # 对于 Groq 快速推理

# 工具配置
export MCP_TOOL_TIMEOUT=120            # 工具执行超时时间（秒）

🌐 可用模式

1. 聊天模式（默认）

提供自然语言界面，支持流式响应和自动工具使用：

# 默认模式，使用 Ollama/gpt-oss 推理模型（无需 API 密钥）
mcp-cli --server sqlite

# 查看 AI 的思考过程，使用推理模型
mcp-cli --server sqlite --model gpt-oss     # 开源推理
mcp-cli --server sqlite --provider openai --model gpt-5  # GPT-5 推理
mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus  # Claude 4.5 推理

# 使用不同的本地模型
mcp-cli --server sqlite --model llama3.3
mcp-cli --server sqlite --model qwen2.5-coder

# 切换到云提供商（需要 API 密钥）
mcp-cli chat --server sqlite --provider openai --model gpt-5
mcp-cli chat --server sqlite --provider anthropic --model claude-4-5-sonnet

# 附带实时浏览器仪表板启动
mcp-cli --server sqlite --dashboard

# 将文件附加到第一条消息
mcp-cli --server sqlite --attach image.png --attach data.csv

2. 交互模式

命令驱动的 Shell 界面，用于直接操作服务器：

mcp-cli interactive --server sqlite

# 使用特定模型
mcp-cli interactive --server sqlite --model gpt-oss       # 本地推理
mcp-cli interactive --server sqlite --provider openai --model gpt-5  # 云 GPT-5

3. 命令模式

适合 Unix 的接口，用于自动化和脚本编写：

# 使用推理模型处理文本
mcp-cli cmd --server sqlite --model gpt-oss --prompt "逐步思考" --input data.txt

# 使用 GPT-5 进行复杂推理
mcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt "分析这些数据" --input data.txt

# 直接执行工具
mcp-cli cmd --server sqlite --tool list_tables --output tables.json

# 流水线友好处理
echo "SELECT * FROM users LIMIT 5" | mcp-cli cmd --server sqlite --tool read_query --input -

4. 直接命令

无需进入交互模式，直接执行单个命令：

# 列出可用工具
mcp-cli tools --server sqlite

# 显示提供商配置
mcp-cli provider list

# 显示当前提供商的可用模型
mcp-cli models

# 显示特定提供商的模型
mcp-cli models openai    # 显示 GPT-5、GPT-4、O3 模型
mcp-cli models anthropic # 显示 Claude 4.5、Claude 3.5 模型
mcp-cli models ollama    # 显示 gpt-oss、llama3.3 等

# Ping 服务器
mcp-cli ping --server sqlite

# 列出资源
mcp-cli resources --server sqlite

# UI 主题管理
mcp-cli theme                     # 显示当前主题并列出可用主题
mcp-cli theme dark                # 切换到深色主题
mcp-cli theme --select            # 交互式主题选择器
mcp-cli theme --list              # 列出所有可用主题

# 令牌存储管理
mcp-cli token backends            # 显示可用存储后端
mcp-cli --token-backend encrypted token list  # 使用特定后端

🌐 MCP 应用程序（交互式浏览器 UI）

MCP 应用程序允许工具服务器提供交互式 HTML UI，并在您的浏览器中渲染。当一个工具带有 _meta.ui 注解指向 UI 资源时，mcp-cli 会自动启动本地 Web 服务器并在您的浏览器中打开该应用程序。

先决条件

# 安装应用程序额外包（添加 websocket 依赖）
pip install "mcp-cli[apps]"

工作原理

1. 连接到提供应用功能的 MCP 服务器
2. 调用带有 _meta.ui 元数据的工具（例如 show_chart、show_table）
3. mcp-cli 自动获取 UI 资源，启动本地服务器，并打开您的浏览器
4. 应用程序通过 WebSocket 实时接收工具结果

示例

# 连接到带有应用功能的服务器
mcp-cli --server view_demo

# 在聊天中请求可视化内容：
> 给我看看销售数据的图表
# 浏览器自动打开交互式图表

# /tools 命令显示哪些工具有应用 UI（APP 列）
> /tools

架构

• 宿主页面 提供沙箱化的 iframe，包含应用程序 HTML
• WebSocket 桥接 在浏览器和 MCP 服务器之间代理 JSON-RPC
• 安全性：iframe 沙箱、CSP 保护、XSS 防护、URL 方案验证
• 可靠性：断开连接时的消息队列、指数退避重连、延迟工具结果交付

完整指南请参阅 MCP 应用程序文档。

🤖 使用聊天模式

聊天模式提供最先进的界面，支持流式响应和智能工具使用。

启动聊天模式

# 简单启动，使用默认推理模型（gpt-oss）
mcp-cli --server sqlite

# 多个服务器
mcp-cli --server sqlite,filesystem

# 搭配先进推理模型
mcp-cli --server sqlite --provider openai --model gpt-5
mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus

聊天命令（斜杠命令）

提供商与模型管理

/provider                           # 显示当前配置（默认：ollama）
/provider list                      # 列出所有提供商
/provider config                    # 显示详细配置
/provider diagnostic               # 测试提供商连接性
/provider set ollama api_base http://localhost:11434  # 配置Ollama端点
/provider openai                   # 切换到OpenAI（需API密钥）
/provider anthropic                # 切换到Anthropic（需API密钥）
/provider openai gpt-5             # 切换到OpenAI GPT-5

# 自定义提供商管理
/provider custom                   # 列出自定义提供商
/provider add localai http://localhost:8080/v1 gpt-4  # 添加自定义提供商
/provider remove localai           # 移除自定义提供商

/model                             # 显示当前模型（默认：gpt-oss）
/model llama3.3                    # 切换到不同Ollama模型
/model gpt-5                       # 切换到GPT-5（若使用OpenAI）
/model claude-4-5-opus             # 切换到Claude 4.5（若使用Anthropic）
/models                            # 列出当前提供商可用的模型

工具管理

/tools                             # 列出可用工具
/tools --all                       # 显示工具详细信息
/tools --raw                       # 显示原始JSON定义
/tools call                        # 交互式工具执行

/toolhistory                       # 显示工具执行历史
/th -n 5                          # 最近5次工具调用
/th 3                             # 第3次调用的详细信息
/th --json                        # 完整历史记录为JSON

服务器管理（运行时配置）

/server                            # 列出所有已配置的服务器
/server list                       # 列出服务器（别名）
/server list all                   # 包括已禁用的服务器

# 运行时添加服务器（持久化至~/.mcp-cli/preferences.json）
/server add <name> stdio <command> [args...]
/server add sqlite stdio uvx mcp-server-sqlite --db-path test.db
/server add playwright stdio npx @playwright/mcp@latest
/server add time stdio uvx mcp-server-time
/server add fs stdio npx @modelcontextprotocol/server-filesystem /path/to/dir

# HTTP/SSE服务器示例，带认证
/server add github --transport http --header "Authorization: Bearer ghp_token" -- https://api.github.com/mcp
/server add myapi --transport http --env API_KEY=secret -- https://api.example.com/mcp
/server add events --transport sse -- https://events.example.com/sse

# 管理服务器状态
/server enable <name>              # 启用已禁用的服务器
/server disable <name>             # 禁用但不删除
/server remove <name>              # 删除用户添加的服务器
/server ping <name>                # 测试服务器连接性

# 服务器详情
/server <name>                     # 显示服务器配置详情

注意：通过/server add添加的服务器存储在~/.mcp-cli/preferences.json中，并在会话间保持。项目服务器则保存在server_config.json中。

多模态附件

/attach image.png                  # 为下一条消息暂存图片
/attach code.py                    # 为下一条消息暂存文本文件
/attach list                       # 显示当前暂存的文件
/attach clear                      # 清空暂存文件
/file data.csv                     # /attach的别名
/image screenshot.heic             # /attach的别名

# 在任何消息中内联引用文件
@file:screenshot.png 描述你看到的内容
@file:data.csv 总结这些数据

# 图片URL自动检测
https://example.com/photo.jpg 这张图片里有什么？

对话管理

/conversation                      # 显示对话历史
/ch -n 10                         # 最近10条消息
/ch 5                             # 第5条消息的详细信息
/ch --json                        # 完整历史记录为JSON

/save conversation.json            # 将对话保存到文件
/compact                          # 总结对话
/clear                            # 清空对话历史
/cls                              # 只清空屏幕

界面定制

/theme                            # 交互式主题选择器，带预览
/theme dark                       # 切换到暗色主题
/theme monokai                    # 切换到monokai主题

# 可用主题：default、dark、light、minimal、terminal、monokai、dracula、solarized
# 主题在会话间保持

令牌管理

/token                            # 列出所有存储的令牌
/token list                       # 显示所有显式存储的令牌
/token set <name>                 # 存储Bearer令牌
/token get <name>                 # 获取令牌详细信息
/token delete <name>              # 删除一个令牌
/token clear                      # 清空所有令牌（需确认）
/token backends                   # 显示可用存储后端

# 示例
/token set my-api                 # 提示输入令牌值（安全）
/token get notion --oauth         # 获取Notion服务器的OAuth令牌
/token list --api-keys            # 只列出提供商的API密钥

令牌存储后端： MCP CLI支持多种安全令牌存储后端：

• Keychain（macOS） - 使用macOS Keychain（macOS默认）
• Windows凭据管理器 - Windows原生存储（Windows默认）
• Secret Service - Linux桌面密钥环（GNOME/KDE）
• 加密文件 - AES-256加密本地文件（跨平台后备）
• HashiCorp Vault - 企业级密钥管理

通过--token-backend覆盖默认后端：

# 使用加密文件存储代替Keychain
mcp-cli --token-backend encrypted token list

# 使用Vault用于企业环境
mcp-cli --token-backend vault token list

更多详细说明请参阅令牌管理指南。

会话控制

/verbose                          # 切换详细/紧凑显示模式（默认：启用）
/confirm                          # 切换工具调用确认模式（默认：启用）
/interrupt                        # 停止正在运行的操作
/server                           # 管理MCP服务器（见上文服务器管理）
/help                            # 显示所有命令
/help tools                       # 特定命令的帮助
/exit                            # 退出聊天模式

完整命令文档请参阅命令系统指南。

聊天功能

带推理过程可视化的流式响应

• 🧠 推理模型：通过 gpt-oss、GPT-5 和 Claude 4 查看 AI 的思考过程
• 实时生成：逐个 token 地观看文本逐步呈现
• 性能指标：每秒字数、响应时间
• 优雅中断：按 Ctrl+C 即可停止流式输出
• 渐进渲染：Markdown 格式随流式传输逐步显示

工具执行

• 自动发现并使用工具
• 并发执行并显示进度条
• 提供详细与简洁两种显示模式
• 完整的执行历史与耗时记录

多模态附件

• 可向任意消息中添加图片、文本文件和音频
• /attach 命令支持暂存、列表与清除（别名：/file、/image）
• 在任意消息中内嵌 @file:路径 引用
• --attach CLI 标志用于首次消息的附件
• 浏览器“+”按钮支持拖放与剪贴板粘贴（配合 --dashboard 使用）
• 仪表板可渲染缩略图、文本预览与音频播放器

供应商集成

• 无缝切换不同供应商
• 针对特定模型的优化
• API 密钥与端点管理
• 健康监测与诊断

🖥️ 使用交互模式

交互模式提供了一个命令行界面，用于直接与服务器交互。

启动交互模式

mcp-cli interactive --server sqlite

交互命令

help                              # 显示可用命令
exit                              # 退出交互模式
clear                             # 清空终端

# 供应商管理
provider                          # 显示当前供应商
provider list                     # 列出供应商
provider anthropic                # 切换供应商
provider openai gpt-5             # 切换到 GPT-5

# 模型管理
model                             # 显示当前模型
model gpt-oss                     # 切换到推理模型
model claude-4-5-opus             # 切换到 Claude 4.5
models                            # 列出可用模型

# 工具操作
tools                             # 列出工具
tools --all                       # 详细工具信息
tools call                        # 交互式工具执行

# 服务器操作
servers                           # 列出服务器
ping                              # Ping 所有服务器
resources                         # 列出资源
prompts                           # 列出提示词

📄 使用命令模式

命令模式提供了类 Unix 的自动化能力。

命令模式选项

--input FILE                      # 输入文件（- 表示标准输入）
--output FILE                     # 输出文件（- 表示标准输出）
--prompt TEXT                     # 提示模板
--tool TOOL                       # 执行特定工具
--tool-args JSON                  # 工具参数，以 JSON 格式传递
--system-prompt TEXT              # 自定义系统提示
--raw                             # 不进行格式化，直接输出原始内容
--single-turn                     # 禁用多轮对话
--max-turns N                     # 对话最大轮次

示例

# 使用推理模型处理文本
echo "分析这些数据" | mcp-cli cmd --server sqlite --model gpt-oss --input - --output analysis.txt

# 使用 GPT-5 进行复杂分析
mcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt "提供战略分析" --input report.txt

# 工具执行
mcp-cli cmd --server sqlite --tool list_tables --raw

# 复杂查询
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# 使用 GNU Parallel 进行批量处理
ls *.txt | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary --prompt "总结: {{input}}"

🔧 供应商配置

Ollama 配置（默认）

Ollama 默认在本地运行于 http://localhost:11434。MCP CLI v0.11.1+ 与 CHUK-LLM v0.16+ 包含 llama.cpp 集成，可自动发现并复用 Ollama 下载的模型，实现 1.53 倍更快的推理速度（311 vs 204 tokens/秒），且无需重新下载。

要使用推理及其他模型：

# 拉取推理及其他模型至 Ollama
ollama pull gpt-oss          # 默认推理模型
ollama pull llama3.3         # 最新 Llama
ollama pull llama3.2         # Llama 3.2
ollama pull qwen3            # Qwen 3
ollama pull qwen2.5-coder    # 编码专注型
ollama pull deepseek-coder   # DeepSeek coder
ollama pull granite3.3       # IBM Granite
ollama pull mistral          # Mistral
ollama pull gemma3           # Google Gemma
ollama pull phi3             # Microsoft Phi
ollama pull codellama        # Code Llama

# 列出可用 Ollama 模型
ollama list

# 配置远程 Ollama 服务器
mcp-cli provider set ollama api_base http://remote-server:11434

云供应商配置

要使用云供应商的高级模型，请配置 API 密钥：

# 配置 OpenAI（用于 GPT-5、GPT-4、O3 模型）
mcp-cli provider set openai api_key sk-your-key-here

# 配置 Anthropic（用于 Claude 4.5、Claude 3.5）
mcp-cli provider set anthropic api_key sk-ant-your-key-here

# 配置 Azure OpenAI（用于企业级 GPT-5）
mcp-cli provider set azure_openai api_key sk-your-key-here
mcp-cli provider set azure_openai api_base https://your-resource.openai.azure.com

# 配置其他供应商
mcp-cli provider set gemini api_key your-gemini-key
mcp-cli provider set groq api_key your-groq-key

# 测试配置
mcp-cli provider diagnostic openai
mcp-cli provider diagnostic anthropic

自定义 OpenAI 兼容供应商

MCP CLI 支持添加自定义 OpenAI 兼容供应商（LocalAI、自定义代理等）：

# 添加自定义供应商（会话间持久化）
mcp-cli provider add localai http://localhost:8080/v1 gpt-4 gpt-3.5-turbo
mcp-cli provider add myproxy https://proxy.example.com/v1 custom-model-1 custom-model-2

# 通过环境变量设置 API 密钥（不会存储在配置中）
export LOCALAI_API_KEY=your-api-key
export MYPROXY_API_KEY=your-api-key

# 列出自定义供应商
mcp-cli provider custom

# 使用自定义供应商
mcp-cli --provider localai --server sqlite
mcp-cli --provider myproxy --model custom-model-1 --server sqlite

# 删除自定义供应商
mcp-cli provider remove localai

# 运行时供应商（仅限本次会话，不持久化）
mcp-cli --provider temp-ai --api-base https://api.temp.com/v1 --api-key test-key --server sqlite

安全提示：API 密钥可安全地存储在操作系统原生密钥链中（macOS Keychain、Windows Credential Manager、Linux Secret Service）或 HashiCorp Vault 中，利用令牌管理系统进行存储。此外，也可使用环境变量，遵循 {供应商名称}_API_KEY 格式，或通过 --api-key 传递以仅限本次会话使用。详情请参阅 令牌管理。

手动配置

~/.chuk_llm/config.yaml 中的 chuk_llm 库配置：

ollama:
  api_base: http://localhost:11434
  default_model: gpt-oss

openai:
  api_base: https://api.openai.com/v1
  default_model: gpt-5

anthropic:
  api_base: https://api.anthropic.com
  default_model: claude-4-5-opus

azure_openai:
  api_base: https://your-resource.openai.azure.com
  default_model: gpt-5

gemini:
  api_base: https://generativelanguage.googleapis.com
  default_model: gemini-2.0-flash

groq:
  api_base: https://api.groq.com
  default_model: llama-3.1-70b

可通过以下方式提供 API 密钥：

1. 安全令牌存储（推荐）—— 存储在操作系统密钥链/保险库中，参见令牌管理
2. 环境变量—— 在您的 Shell 中导出或添加到 ~/.chuk_llm/.env：

OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here
AZURE_OPENAI_API_KEY=sk-your-azure-key-here
GEMINI_API_KEY=your-gemini-key
GROQ_API_KEY=your-groq-key

3. 命令行—— 通过 --api-key 传递，仅用于当前会话（不持久化）

📂 服务器配置

MCP CLI 支持两种类型的服务器配置：

1. 项目服务器 (server_config.json)：共享的项目级配置
2. 用户服务器 (~/.mcp-cli/preferences.json)：个人运行时添加的服务器，跨会话持久化

配置文件发现

MCP CLI 按以下优先级顺序查找 server_config.json：

1. 显式路径，通过 --config-file 选项指定：

   mcp-cli --config-file /path/to/custom-config.json
   

2. 当前目录—— 当从项目目录运行时自动检测：

   cd /path/to/my-project
   mcp-cli --server sqlite    # 如果存在 ./server_config.json，则使用该文件
   

3. 内置默认值—— 当通过 uvx 运行或从任何没有本地配置的目录运行时：

   uvx mcp-cli --server cloudflare_workers    # 使用打包的 server_config.json
   

这意味着您可以：

• 覆盖每个项目：在项目目录中放置一个 server_config.json，包含特定于项目的服务器配置
• 全局使用默认值：从任意位置运行 uvx mcp-cli，获取内置默认服务器
• 明确自定义：使用 --config-file 指定任意配置文件位置

内置默认服务器

MCP CLI v0.11.1+ 在内置的 server_config.json 中附带了一组扩展的预配置服务器：

服务器	类型	描述	配置
sqlite	STDIO	SQLite 数据库操作	uvx mcp-server-sqlite --db-path test.db
echo	STDIO	测试用回声服务器	uvx chuk-mcp-echo stdio
math	STDIO	数学计算	uvx chuk-mcp-math-server
playwright	STDIO	浏览器自动化	npx @playwright/mcp@latest
brave_search	STDIO	通过 Brave API 的网页搜索	需要 BRAVE_API_KEY 令牌
notion	HTTP	Notion 工作区集成	https://mcp.notion.com/mcp (OAuth)
cloudflare_workers	HTTP	Cloudflare Workers 绑定	https://bindings.mcp.cloudflare.com/mcp (OAuth)
monday	HTTP	Monday.com 集成	https://mcp.monday.com/mcp (OAuth)
linkedin	HTTP	LinkedIn 集成	https://linkedin.chukai.io/mcp
weather	HTTP	天气数据服务	https://weather.chukai.io/mcp

注意：HTTP 服务器和基于 API 的服务器需要认证。请使用令牌管理系统配置访问令牌。

要使用这些服务器：

# 从任意位置使用内置服务器
uvx mcp-cli --server sqlite
uvx mcp-cli --server echo
uvx mcp-cli --server math
uvx mcp-cli --server playwright

# 基于 API 的服务器需要令牌
mcp-cli token set brave_search --type bearer
uvx mcp-cli --server brave_search

# HTTP/OAuth 服务器需要 OAuth 认证
uvx mcp-cli token set notion --oauth
uvx mcp-cli --server notion

# 同时使用多个服务器
uvx mcp-cli --server sqlite,math,playwright

项目配置

创建一个包含 MCP 服务器配置的 server_config.json 文件：

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": ["-m", "mcp_server.sqlite_server"],
      "env": {
        "DATABASE_PATH": "database.db"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
      "env": {}
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "${TOKEN:bearer:brave_search}"
      }
    },
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKEN:bearer:notion}"
      }
    }
  }
}

安全令牌替换

MCP CLI 支持从安全存储自动替换令牌，使用 ${TOKEN:namespace:name} 语法：

语法：${TOKEN:<namespace>:<token-name>}

示例：

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "${TOKEN:bearer:brave_search}"
      }
    },
    "api-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKEN:bearer:my_api}",
        "X-API-Key": "${TOKEN:api-key:my_service}"
      }
    }
  }
}

令牌存储：

# 安全存储令牌（绝不在配置文件中）
mcp-cli token set brave_search --type bearer
# 根据提示输入令牌值（隐藏输入）

mcp-cli token set my_api --type bearer --value "your-token-here"

# 令牌存储在操作系统原生安全存储中：
# - macOS：钥匙串
# - Windows：凭据管理器
# - Linux：Secret Service（GNOME Keyring/KWallet）

支持的位置：

• env：适用于 STDIO 服务器的环境变量
• headers：适用于 HTTP/SSE 服务器的 HTTP 头部

命名空间：

• bearer：Bearer 令牌（默认为 --type bearer）
• api-key：API 密钥（默认为 --type api-key）
• oauth：OAuth 令牌（自动）
• generic：自定义令牌

优势：

• ✅ 绝不在配置文件中存储 API 密钥
• ✅ 安全共享 server_config.json（无敏感信息）
• ✅ 令牌加密存储在操作系统原生安全存储中
• ✅ 适用于所有传输类型（STDIO、HTTP、SSE）

完整文档请参阅令牌管理指南。

运行时服务器管理

在运行时动态添加服务器，无需编辑配置文件：

# 添加 STDIO 服务器（最常见）
mcp-cli
> /server add sqlite stdio uvx mcp-server-sqlite --db-path mydata.db
> /server add playwright stdio npx @playwright/mcp@latest
> /server add time stdio uvx mcp-server-time

# 添加带身份验证的HTTP服务器
> /server add github --transport http --header "Authorization: Bearer ghp_token" -- https://api.github.com/mcp
> /server add myapi --transport http --env API_KEY=secret -- https://api.example.com/mcp

# 添加SSE（服务器发送事件）服务器
> /server add events --transport sse -- https://events.example.com/sse

# 管理服务器
> /server list                     # 显示所有服务器
> /server disable sqlite           # 临时禁用
> /server enable sqlite            # 重新启用
> /server remove myapi             # 移除用户添加的服务器

**要点：**
- 用户添加的服务器会持久化保存在~/.mcp-cli/preferences.json中
- 即使应用重启也能保留
- 可以在不移除的情况下启用/禁用
- 支持STDIO、HTTP和SSE传输方式
- 支持环境变量和头部信息进行身份验证

## 📈 高级使用示例

### 推理模型对比

```bash
# 对比不同模型的推理过程
> /provider ollama
> /model gpt-oss
> 逐步思考这个问题：如果一列火车下午3点从纽约出发……
[查看gpt-oss的完整思考过程]

> /provider openai
> /model gpt-5
> 逐步思考这个问题：如果一列火车下午3点从纽约出发……
[查看GPT-5的推理思路]

> /provider anthropic
> /model claude-4-5-opus
> 逐步思考这个问题：如果一列火车下午3点从纽约出发……
[查看Claude 4.5的分析过程]

基于推理的本地优先工作流

# 从默认的Ollama/gpt-oss开始（无需API密钥）
mcp-cli chat --server sqlite

# 对复杂问题使用推理模型
> 逐步思考这个数据库优化问题
[gpt-oss展示其完整的思考过程后再作答]

# 对不同任务尝试不同的本地模型
> /model llama3.3              # 通用型
> /model qwen2.5-coder         # 用于编码任务
> /model deepseek-coder        # 替代编码模型
> /model granite3.3            # IBM的模型
> /model gpt-oss               # 回到推理模型

# 需要时切换到云端（需提供API密钥）
> /provider openai
> /model gpt-5
> 复杂的企业架构设计……

> /provider anthropic
> /model claude-4-5-opus
> 详细的战略分析……

> /provider ollama
> /model gpt-oss
> 继续本地处理……

多提供商工作流

# 从本地推理开始（默认，无需API密钥）
mcp-cli chat --server sqlite

# 对比不同提供商的响应
> /provider ollama
> 优化这个SQL查询的最佳方法是什么？

> /provider openai gpt-5        # 需要API密钥
> 优化这个SQL查询的最佳方法是什么？

> /provider anthropic claude-4-5-sonnet  # 需要API密钥
> 优化这个SQL查询的最佳方法是什么？

# 发挥各提供商的优势
> /provider ollama gpt-oss      # 本地推理，隐私保护
> /provider openai gpt-5        # 高级推理
> /provider anthropic claude-4-5-opus  # 深度分析
> /provider groq llama-3.1-70b  # 超快响应

带推理的复杂工具工作流

# 对复杂数据库任务使用推理模型
> /model gpt-oss
> 我需要分析我们的数据库性能。先想想应该检查什么。

[gpt-oss展示思考过程：“首先，我应该检查表结构，然后是索引，再看查询模式……”]
[工具：list_tables] → products, customers, orders

> 现在分析索引并提出优化建议
[gpt-oss思考索引分析过程]
[工具：describe_table] → 展示当前索引
[工具：read_query] → 分析查询模式

> 根据你的分析制定优化方案
[完整的推理过程及具体建议]

自动化与脚本编写

# 使用不同模型进行批量处理
for file in data/*.csv; do
  # 使用推理模型进行分析
  mcp-cli cmd --server sqlite \
    --model gpt-oss \
    --prompt "分析这些数据并思考其中的规律" \
    --input "$file" \
    --output "analysis/$(basename "$file" .csv)_reasoning.txt"
  
  # 使用编码模型生成脚本
  mcp-cli cmd --server sqlite \
    --model qwen2.5-coder \
    --prompt "生成Python代码来处理这些数据" \
    --input "$file" \
    --output "scripts/$(basename "$file" .csv)_script.py"
done

# 带推理的流水线
cat complex_problem.txt | \
  mcp-cli cmd --model gpt-oss --prompt "逐步思考" --input - | \
  mcp-cli cmd --model llama3.3 --prompt "总结关键点" --input - > solution.txt

性能监控

# 检查提供商和模型的性能
> /provider diagnostic
提供商诊断
提供商      | 状态      | 响应时间 | 功能      | 模型
ollama        | ✅ 就绪    | 56ms         | 📡🔧         | gpt-oss, llama3.3, qwen3, ...
openai        | ✅ 就绪    | 234ms        | 📡🔧👁️      | gpt-5, gpt-4o, o3, ...
anthropic     | ✅ 就绪    | 187ms        | 📡🔧         | claude-4-5-opus, claude-4-5-sonnet, ...
azure_openai  | ✅ 就绪    | 198ms        | 📡🔧👁️      | gpt-5, gpt-4o, ...
gemini        | ✅ 就绪    | 156ms        | 📡🔧👁️      | gemini-2.0-flash, ...
groq          | ✅ 就绪    | 45ms         | 📡🔧         | llama-3.1-70b, ...

# 查看可用模型
> /models
适用于ollama的模型（当前提供商）
模型                | 状态
gpt-oss             | 当前及默认（推理）
llama3.3            | 可用
llama3.2            | 可用
qwen2.5-coder       | 可用
deepseek-coder      | 可用
granite3.3          | 可用
...还有6个更多

# 监控带推理的工具执行
> /verbose
> /model gpt-oss
> 分析数据库并优化最慢的查询
[显示完整的思考过程]
[工具执行并计时]

🔍 故障排除

常见问题

1. Ollama 未运行（默认提供者）：

   # 启动 Ollama 服务
   ollama serve
   
   # 或者检查是否正在运行
   curl http://localhost:11434/api/tags
   

2. 模型未找到：

   # 对于 Ollama（默认），先拉取模型
   ollama pull gpt-oss      # 理论推理模型
   ollama pull llama3.3     # 最新 Llama 模型
   ollama pull qwen2.5-coder # 编码模型
   
   # 列出可用模型
   ollama list
   
   # 对于云提供商，查看支持的模型
   mcp-cli models openai     # 显示 GPT-5、GPT-4、O3 模型
   mcp-cli models anthropic  # 显示 Claude 4.5、Claude 3.5 模型
   

3. 提供者未找到或 API 密钥缺失：

   # 查看可用提供者
   mcp-cli provider list
   
   # 对于云提供商，设置 API 密钥
   mcp-cli provider set openai api_key sk-your-key
   mcp-cli provider set anthropic api_key sk-ant-your-key
   
   # 测试连接
   mcp-cli provider diagnostic openai
   

4. 与 Ollama 的连接问题：

   # 检查 Ollama 是否正在运行
   ollama list
   
   # 测试连接
   mcp-cli provider diagnostic ollama
   
   # 如需自定义端点，可进行配置
   mcp-cli provider set ollama api_base http://localhost:11434
   

调试模式

启用详细日志记录以进行故障排除：

mcp-cli --verbose chat --server sqlite
mcp-cli --log-level DEBUG interactive --server sqlite

# 将调试日志写入轮转文件（密钥自动脱敏）
mcp-cli --log-file ~/.mcp-cli/logs/debug.log --server sqlite

🔒 安全考虑

隐私与本地优先

• 默认本地运行：Ollama 与 gpt-oss 在本地运行，确保您的数据隐私
• 无需云端：完全功能无需外部 API 依赖

令牌与认证安全

• 安全令牌存储：令牌存储在操作系统原生凭据存储中（macOS Keychain、Windows Credential Manager、Linux Secret Service），标识为“mcp-cli”服务
• 多种存储后端：根据安全需求，可选择钥匙串、加密文件或 HashiCorp Vault
• API 密钥：仅对云提供商（OpenAI、Anthropic 等）需要，使用令牌管理系统安全存储
• OAuth 2.0 支持：使用 PKCE 和资源指示器（RFC 7636、RFC 8707）为 MCP 服务器提供安全认证

日志安全

• 密钥脱敏：所有日志输出（控制台和文件）自动脱敏 Bearer 令牌、API 密钥（sk-*）、OAuth 访问令牌和授权头
• 轮转文件日志：可选 --log-file 以 JSON 格式记录，10MB 轮转，保留 3 个备份文件

执行安全

• 工具验证：所有工具调用在执行前均经过验证
• 超时保护：可配置超时防止操作挂起（v0.13+）
• 熔断器：自动检测并恢复失败，防止级联故障（v0.13+）
• 服务器隔离：每个服务器独立运行
• 文件访问：可通过 --disable-filesystem 禁用文件系统访问
• 传输监控：自动检测连接失败并发出警告（v0.11+）

MCP 应用程序安全

• iframe 沙箱：应用程序在沙箱 iframe 中运行，权限受限
• 内容安全策略：服务器提供的 CSP 域名经过验证和净化
• XSS 防护：工具名称和用户输入内容在模板注入前进行 HTML 转义
• URL 方案验证：ui/open-link 仅允许 http:// 和 https:// 方案
• 工具名称验证：桥接拒绝不符合 MCP 规范字符集的工具名称

🚀 性能特性

LLM 提供者性能（v0.16+）

• 导入速度提升 52 倍：通过懒加载，从 735ms 降至 14ms
• 客户端创建速度提升 112 倍：自动线程安全缓存
• llama.cpp 集成：推理速度提升 1.53 倍（311 vs 204 tokens/sec），自动复用 Ollama 模型
• 动态模型发现：零开销基于能力的模型选择

工具执行性能（v0.13+）

• 生产中间件：超时、重试指数退避、熔断器和结果缓存
• 并发工具执行：多个工具可同时运行并协调
• 连接健康监控：自动检测并恢复传输失败
• 优化工具管理器：从 2000+ 行减少至约 800 行，同时保持全部功能

运行时性能

• 本地处理：默认 Ollama 提供者最小化延迟
• 推理可见性：通过 gpt-oss、GPT-5、Claude 4 可查看 AI 思考过程
• 流式响应：实时响应生成
• 连接池：高效复用客户端连接
• 缓存：工具元数据和提供者配置被缓存
• 异步架构：全程非阻塞操作

📦 依赖项

核心依赖项按功能分组：

• cli：终端 UI 和命令框架（Rich、Typer、chuk-term）
• dev：开发工具、测试实用程序、代码检查
• chuk-tool-processor v0.22+：生产级工具执行，带中间件、多种执行策略和可观测性
• chuk-llm v0.17+：统一 LLM 提供者，支持动态模型发现、基于能力的选择和 llama.cpp 集成
• chuk-term：增强终端 UI，支持主题、提示和跨平台

安装特定功能：

pip install "mcp-cli[cli]"        # 基本 CLI 功能
pip install "mcp-cli[cli,dev]"    # 带开发工具的 CLI
pip install "mcp-cli[apps]"       # MCP 应用程序（交互式浏览器 UI）

🤝 贡献

我们欢迎贡献！请参阅我们的 贡献指南 了解详情。

开发环境搭建

git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
pip install -e ".[cli,dev]"
pre-commit install

演示脚本

探索 MCP CLI 的各项功能：

# 命令模式演示

# 通用命令模式功能（bash）
bash examples/cmd_mode_demo.sh

# 命令模式与 LLM 集成（bash）
bash examples/cmd_mode_llm_demo.sh

# Python 集成示例
uv run examples/cmd_mode_python_demo.py

# 自定义提供者管理演示

# 交互式 walkthrough 演示（教育用途）
uv run examples/custom_provider_demo.py

# 实际推理工作演示（需 OPENAI_API_KEY）
uv run examples/custom_provider_working_demo.py

# 简单 Shell 脚本演示（需 OPENAI_API_KEY）
bash examples/custom_provider_simple_demo.sh

# 终端管理功能（chuk-term）
uv run examples/ui_terminal_demo.py

# 输出系统与主题（chuk-term）
uv run examples/ui_output_demo.py

# 流式 UI 能力（chuk-term）
uv run examples/ui_streaming_demo.py

运行测试

pytest
pytest --cov=mcp_cli --cov-report=html

📜 许可证

本项目采用 Apache License 2.0 许可证——详情请参阅 LICENSE 文件。

🙏 感谢

• CHUK 工具处理器 - 带中间件和可观测性的生产级异步工具执行框架
• CHUK-LLM - 统一的大型语言模型提供商，支持动态模型发现、llama.cpp 集成以及 GPT-5 和 Claude 4.5（v0.17+）
• CHUK-Term - 增强型终端 UI，支持主题和跨平台
• Rich - 美丽的终端格式化工具
• Typer - 命令行界面框架
• Prompt Toolkit - 交互式输入工具

🔗 相关项目

• 模型上下文协议 - 核心协议规范
• MCP 服务器 - MCP 官方服务器实现
• CHUK 工具处理器 - 带中间件和可观测性的生产级工具执行框架
• CHUK-LLM - 大型语言模型提供商抽象层，支持动态模型发现、GPT-5、Claude 4.5、O3 系列以及 llama.cpp 集成
• CHUK-Term - 终端 UI 库，支持主题和跨平台

MCP CLI 快速上手指南

MCP CLI 是一个功能强大的命令行工具，用于与模型上下文协议（Model Context Protocol）服务器交互。它支持本地隐私优先的运行模式（默认集成 Ollama），并提供对话管理、工具调用、执行计划及多模态附件等高级功能。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS, 或 Windows (WSL 推荐)。
• Python 版本：Python 3.10 或更高版本。
• 本地模型运行器（可选但推荐）：
  • 若需使用默认的本地隐私模式，请安装 Ollama。
  • 国内用户可访问 Ollama 中国镜像或社区加速方案进行安装。
  • 拉取默认推理模型：

    ollama pull gpt-oss
    

    (注：若 gpt-oss 获取困难，可替换为 llama3.3 或其他本地模型，并在运行时指定)

安装步骤

推荐使用 pip 进行安装。国内开发者建议使用清华或阿里镜像源以加速下载。

使用官方源安装：

pip install mcp-cli

使用国内镜像源安装（推荐）：

pip install mcp-cli -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，可通过以下命令验证版本：

mcp-cli --version

基本使用

1. 启动聊天模式（默认配置）

默认情况下，MCP CLI 会自动连接本地 Ollama 服务并使用 gpt-oss 推理模型。无需配置 API Key 即可开始对话。

mcp-cli

进入交互界面后，您可以直接输入自然语言问题。系统会自动发现并调用可用的工具。

2. 指定模型或提供商

如果您想使用其他模型（如 llama3.3）或云端提供商（如 OpenAI），可以在启动时通过参数指定：

# 使用特定的 Ollama 模型
mcp-cli --model llama3.3

# 使用 OpenAI 提供商 (需预先配置环境变量 OPENAI_API_KEY)
mcp-cli --provider openai --model gpt-4o

3. 常用交互命令

在聊天界面中，可以使用以下斜杠命令增强体验：

• 查看令牌用量：

  /usage
  

• 添加多模态附件（图片、代码文件等）：

  /attach path/to/image.png
  

  或者在消息中直接引用：

  请分析这张图片 @file:path/to/image.png
  

• 执行计划管理（创建和运行多步任务计划）：

  /plan create 帮我分析当前目录下的所有 Python 文件并生成报告
  

• 导出对话：

  /export conversation.md
  

4. 启用实时仪表盘（可选）

若希望获得可视化的浏览器界面，实时监控对话流、工具调用和执行计划，可添加 --dashboard 标志启动：

mcp-cli --dashboard

启动后，终端会提供一个本地 URL，在浏览器中打开即可看到包含消息气泡、令牌统计和 DAG 执行图的交互式面板。

5. 脚本化/非交互模式

适用于自动化脚本或管道操作：

echo "列出当前目录文件" | mcp-cli --mode command