mcp-client-for-ollama
jonigl/mcp-client-for-ollama加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象你正在调试一个复杂的多步骤 Agent 流程——传统的做法是打开 Jupyter Notebook，一边改 prompt 一边手动测试工具调用。但如果你有一套现成的 MCP Server，想要快速验证它们是否工作正常，或者想要一个可以随时切换模型、可视化调试的交互界面，该怎么办？
ollmcp（MCP Client for Ollama）正是为这个场景而生的工具。它不是一个普通的命令行工具，而是一个功能完整的 MCP 协议终端客户端，专门为 Ollama 本地大模型打造，支持同时连接多个 MCP 服务器，在 TUI（终端用户界面）中完成从工具调用、Agent 自主执行到流式输出的全链路调试。
ollmcp TUI 界面概览，展示模型列表与可用工具
2024 年底，Anthropic 正式发布了 Model Context Protocol（MCP）协议规范，旨在解决 AI 模型与外部工具之间的标准化通信问题。与 OpenAI 的 Function Calling 类似，但 MCP 的野心更大——它不仅定义工具调用格式，还包括 Prompts（提示模板） 和 Resources（外部资源） 两大原语，构建了一套完整的 AI 上下文扩展协议栈。
然而，MCP 生态面临一个现实问题：客户端选择有限。官方仅提供了 TypeScript SDK，而 Python 开发者若想在本地快速实验，往往需要自行实现一个简化版 MCP 客户端。ollmcp 的作者 Jonathan Löwenstern 从这个痛点出发，用 Python 实现了一个功能完整、交互友好的 MCP 客户端，深度集成 Ollama 作为推理后端。
项目于 2025 年 4 月创建，2026 年 6 月已迭代至 v0.29.1（最新提交 2026-06-11），维护非常活跃。作者 Jonathan Gastón Löwenstern 是唯一的主要贡献者（149 commits），同时接受社区 PR，整体代码质量高，文档详尽，遵循 MIT 许可证。
ollmcp 的功能远不止"连接 Ollama 和 MCP 服务器"这么简单。它的核心能力可以分为以下几个层次：
ollmcp 是目前少数完整支持 MCP 三大原语的客户端之一：
Tools（工具）：浏览 MCP 服务器暴露的所有可用工具，带参数类型提示，Human-in-the-Loop 模式下每个工具执行前需要用户确认，防止恶意操作
Prompts（提示模板）：从 MCP 服务器获取预定义提示，支持参数输入和预览，可安全回滚
Resources（资源）：读取 MCP 服务器提供的上下文数据，包括文件、文档、结构化数据
这种完整性让 ollmcp 不仅仅是一个调试工具，更是一个MCP 协议的完整客户端实现。
ollmcp 最强大的功能之一是 Agent 模式。当模型判断需要调用工具时，它会自动执行工具调用，并将结果反馈给模型，形成一个自主循环。用户可以设置最大循环次数来防止无限循环（常见于模型卡在反复调用同一工具的场景）。
ollmcp 支持同时连接多个 MCP 服务器，STDIO、SSE、Streamable HTTP 三种传输类型均支持，用户可以在同一 TUI 中自由切换不同服务器的工具集。这对于 MCP Server 开发者来说特别有用——无需启动多个客户端，即可测试多个服务器的协同工作。
ollmcp 支持 Ollama 的流式响应，通过 rich 库实现美观的终端渲染。还会显示性能指标面板，包括首次响应时间（TTFT）、每秒 token 数（tokens/s）、总耗时等，帮助开发者分析模型推理效率。
ollmcp 模型选择界面，支持切换不同 Ollama 模型
ollmcp 的代码结构非常清晰，主模块位于 mcp_client_for_ollama/ 目录下：
| 目录 | 职责 |
|------|------|
| mcp_client_for_ollama/models/ | 模型抽象层 |
| mcp_client_for_ollama/server/ | MCP 服务器通信 |
| mcp_client_for_ollama/transport/ | 传输层（STDIO / SSE / Streamable HTTP） |
| mcp_client_for_ollama/tools/ | 工具处理逻辑 |
| mcp_client_for_ollama/prompts/ | 提示模板处理 |
| mcp_client_for_ollama/resources/ | 外部资源处理 |
| mcp_client_for_ollama/config/ | 配置管理 |
| mcp_client_for_ollama/utils/ | 工具函数 |
关键依赖：
mcp (≥1.25 <1.28)：Anthropic 官方 MCP Python SDK，协议基础
ollama (≈0.6.0)：Ollama Python 客户端，对接本地推理服务
prompt-toolkit (≥3.0.52)：构建交互式 TUI
rich (≥14.2.0)：终端美化渲染
typer (≥0.21.0)：CLI 参数解析
项目采用双包结构：mcp-client-for-ollama（主包）+ ollmcp（CLI 别名包）。版本同步通过 scripts/bump_version.py 脚本管理，确保主包和 CLI 包的版本号始终一致。GitHub Actions CI 包含依赖审查、代码检查，测试框架使用 pytest。
安装极简：
pip install mcp-client-for-ollama
前提条件：
Python ≥ 3.10
Ollama 服务运行中（ollama serve）
至少一个 MCP Server 配置文件（JSON 格式）
# 默认连接本地 Ollama
mcp-client-for-ollama
# 指定 Ollama 地址（远程）
mcp-client-for-ollama --ollama-url http://192.168.1.100:11434
# 加载 MCP Server 配置
mcp-client-for-ollama --server-config ~/mcp-servers/filesystem.json
TUI 快捷键：方向键浏览、F2 进入 Agent 模式、F3 性能面板、F4 历史记录、Tab 切换服务器。
ollmcp 并非完美。以下几点值得注意：
无 Web UI：纯 TUI 工具，团队协作场景受限
无容器化：没有 Dockerfile 或 docker-compose，无法在隔离环境中快速部署
强依赖 Ollama：虽然理论上可对接其他 MCP-compatible 后端，但项目深度绑定了 Ollama
单一维护者风险：主包作者一人主导（149 commits），尽管有社区贡献，长期维护存在风险
MCP 协议迭代压力：协议仍在快速演进（仓库当前使用 mcp ≥1.25 <1.28），需要持续跟进
ollmcp 的出现填补了 MCP 生态在 Python/TUI 客户端 方向的空白。随着本地大模型能力越来越强（Llama 4、Mistral Large 等），开发者对本地 AI 工具链的需求日益增长——既要有隐私保障（数据不离开本地），又要有丰富的工具生态。MCP 协议 + Ollama + ollmcp 构成了一套完整的本地 Agent 开发环境。
从趋势看，MCP 正在成为 AI 工具调用的事实标准（GitHub 已在导航栏新增了 MCP Registry 入口），ollmcp 作为这一生态中的客户端基础设施，具有重要的参考价值和实用价值。随着 v0.29.1 的发布和 v0.29.0 引入的图片内容 MCP 工具响应支持，项目正稳步向更丰富的多模态能力演进。