mcpField
M
MCP Client for Ollama (ollmcp)

MCP Client for Ollama (ollmcp)

本地服务
github.com/joniglAI 与智能体8344 周前更新
代码仓库

关于 MCP Client for Ollama (ollmcp)

ollmcp 是一个基于终端界面（TUI）的 Python 客户端，用于将本地 Ollama 模型连接到一个或多个 MCP 服务。它面向希望在命令行中管理 MCP 服务和模型的用户，并支持 Agent 模式与人工审批工具调用。

主要功能

  1. 01Agent 模式下的迭代式工具调用
  2. 02同时连接多个 MCP 服务
  3. 03支持 STDIO、SSE 与 Streamable HTTP 传输
  4. 04浏览与调用 MCP 工具、提示词和资源
  5. 05工具执行前的人工审批（HIL）
  6. 06运行时切换 Ollama 模型并配置模型参数

适用场景

  1. 01在终端中使用本地 Ollama 模型调用 MCP 工具
  2. 02通过命令行添加与管理 MCP 服务配置
  3. 03在开发过程中调试 MCP 服务并热重载

MCP 相关

该项目是 MCP 客户端，负责连接本地 MCP 服务，发现并调用其工具、提示词与资源，并可通过 ollmcp mcp add 命令管理服务配置。

#open-source#ai#mcp#sse#model-selection#stdio#command-line-tool#terminal-based#pypi-package#tool-management#chat-interface#llm#generative-ai#local-llm#ollama#model-context-protocol#mcp-server#mcp-client

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

README 配图

一个简单而强大的 Python 客户端，可通过 Ollama 与 Model Context Protocol（MCP）服务交互，让你借助本地大模型执行高级工具操作。

English | 简体中文 | Español

Ollama 的 MCP 客户端（ollmcp）

Pepy Total Downloads Python 3.11+ PyPI - Python Version PyPI - Python Version CI

赞助方
Atlas Cloud
请在赞助方一节了解如何将 Atlas Cloud 与 ollmcp 搭配使用

Ollama 的 MCP 客户端演示

🎥 观看 Asciinema 录制的演示

## 目录

概述

Ollama 的 MCP 客户端（ollmcp）是一款现代化的交互式终端应用（TUI），专为 harness engineering 打造，可将本地 Ollama 大模型连接到一个或多个 Model Context Protocol（MCP）服务。它全面支持 MCP 的核心原语（工具、提示词和资源），提供一个由你掌控、由 Agent 执行任务的受控终端环境。凭借丰富且易用的界面，你无需编写代码，即可安全地实时管理配置。无论是构建、测试还是探索，这款客户端都能通过模糊自动补全、高级模型配置、用于快速开发的 MCP 服务热重载，以及严格的 Human-in-the-Loop 安全控制等功能，简化你的工作流。

功能

  • 🤖 Agent 模式：当模型请求多次调用工具时，迭代执行工具，并可配置循环次数上限；达到上限时提供交互式选项（继续、收尾或中止）
  • 🌐 多服务支持：同时连接多个 MCP 服务
  • 🚀 多种传输类型：支持 STDIO、SSE 和 Streamable HTTP 服务连接
  • 📋 MCP 提示词支持：浏览、调用和管理 MCP 服务中的提示词，支持收集参数、预览和安全回滚
  • 📦 MCP 资源支持：浏览并读取 MCP 服务中的上下文数据，包括文件、文档和结构化数据
  • ☁️ Ollama Cloud 支持：可无缝使用 Ollama Cloud 模型调用工具，在使用本地 MCP 工具的同时访问强大的云端托管模型
  • 🌍 多种大模型提供商：使用 Ollama（默认）或兼容 OpenAI 的提供商（OpenAI、OpenRouter、DeepSeek 等），并按提供商记住连接设置
  • 🎨 丰富的终端界面：采用现代样式的交互式控制台 UI
  • 🌊 流式响应：实时查看模型生成的输出
  • 📝 回答显示模式：流式输出时，可在纯文本、Markdown、两者兼有或 Markdown（代码块）视图之间切换
  • 🛠️ 工具管理：在聊天会话中启用或禁用特定工具或整个服务
  • 🧑‍💻 人在回路中（HIL）：在工具执行前进行审核和批准，以增强控制力和安全性
  • 🎮 高级模型配置：微调 15+ 个模型参数，包括上下文窗口大小、温度、采样、重复控制等
  • 💬 系统提示词自定义：定义并编辑系统提示词，以控制模型的行为和角色设定
  • 🧠 上下文窗口控制：调整上下文窗口大小（num_ctx），以处理更长的对话和复杂任务
  • 🎨 增强的工具显示：以精美、结构化的方式呈现工具执行过程，并提供 JSON 语法高亮
  • 🧠 上下文管理：通过可配置的保留设置管理对话记忆
  • 🤔 思考模式：为支持的模型（例如 gpt-oss、deepseek-r1、qwen3 等）提供高级推理能力，并显示思考过程
  • 💪 推理强度级别：为支持的模型设置推理强度：自动、最低、低、中、高或 xhigh
  • 🖼️ 视觉工具支持：工具返回的图像会自动转发给具备视觉能力的模型
  • 🗣️ 跨语言支持：无缝使用 Python 和 JavaScript MCP 服务
  • 📜 历史记录管理：查看完整对话历史、导出为 JSON 以供备份或分析，并导入之前的会话以延续对话
  • 🔍 自动发现：自动查找并使用 Claude 现有的 MCP 服务配置
  • 🔁 动态切换模型：无需重启即可在任意已安装的 Ollama 模型之间切换
  • 💾 配置持久化：在不同会话之间保存和加载工具偏好设置及模型设置
  • 🔄 服务重载：开发期间热重载 MCP 服务，无需重启客户端
  • ✨ 模糊自动补全：支持交互式方向键操作的命令自动补全，并显示说明
  • 🏷️ 动态提示：显示当前模型、思考模式和已启用的工具
  • 📊 性能指标：每次查询后提供详细的模型性能数据，包括耗时和令牌数
  • 🔌 即插即用：可立即与符合 MCP 标准的工具服务配合使用
  • 🔔 更新通知：自动检测是否有新版本可用
  • 🖥️ 基于 Typer 的现代命令行：提供分组的选项、Shell 自动补全和改进的帮助输出
  • ⏹️ 中止生成：响应流式输出期间，随时按“a”即可中止模型生成

要求

  • Python 3.11+（安装指南）
  • 在本地运行的 Ollama（安装指南）
    • 安装后，运行 ollama list 查看可用模型。如果尚未安装任何模型，可以使用 ollama pull <model_name> 拉取一个。例如，ollama pull gemma4:latest。
  • UV 包管理器（安装指南）

快速开始

通过 pip 安装 ollmcp，添加 MCP 服务，然后运行客户端：

# Install ollmcp via uv
uv tool install --upgrade ollmcp
# or via pip
pip install --upgrade ollmcp
# Add an MCP server (example: playwright stdio server)
ollmcp mcp add playwright -- npx @playwright/mcp@latest
# Run the client (check optional flags with `ollmcp --help`)
ollmcp # once running, use /help for interactive commands

安装选项

选项 1： 使用 uv 安装并运行（推荐）

uv tool install --upgrade ollmcp
ollmcp

选项 2： 使用 pip 安装并运行

pip install --upgrade ollmcp
ollmcp

选项 3： 仅运行，不安装（需要 uv 包管理器）

uvx ollmcp

选项 4： 从源代码安装，并使用虚拟环境运行

git clone https://github.com/jonigl/mcp-client-for-ollama.git
cd mcp-client-for-ollama
uv run -m mcp_client_for_ollama

故障排除

Could not find a version that satisfies the requirement ollmcp (from versions: none)

这几乎总是意味着你正在使用的 Python 版本低于所需的 3.11+。这在 macOS 上很常见，因为系统 Python（/usr/bin/python3）或 Xcode 捆绑的 Python 可能是 3.9 或更旧版本。如果没有符合 requires-python >= 3.11 的版本，pip 就会过滤掉所有版本，并报告容易误导的“from versions: none”。

先检查你的版本：

python3 --version   # must be 3.11 or newer

然后使用较新的 Python 安装。最简单的方法是使用 uv，它会自动为你下载合适的 Python：

uv tool install --upgrade ollmcp   # recommended, installs the CLI in an isolated environment
# or, if you prefer pip, make sure to use a Python 3.11+ interpreter:
python3.11 -m pip install --upgrade ollmcp
# Then run the client:
ollmcp

请参阅安装选项。

error: externally-managed-environment (PEP 668)

在较新的 Debian/Ubuntu（Python 3.12+）上，系统 pip 会被有意锁定，以保护由操作系统管理的包，因此会阻止执行 pip install ollmcp。这是系统策略（PEP 668），并非 ollmcp 的问题。请将其安装到隔离环境中：

uv tool install --upgrade ollmcp   # recommended, installs the CLI in an isolated environment
# or, if you prefer pip, use a virtual environment:
python3.11 -m venv ollmcp-env
source ollmcp-env/bin/activate
python3.11 -m pip install --upgrade ollmcp
# Then run the client:
ollmcp

请参阅安装选项。

警告

避免使用 pip install --break-system-packages ollmcp。虽然这样可行，但它会将包安装到系统 Python 中，可能会破坏操作系统依赖的包。

通过 CLI 管理 MCP 服务

ollmcp 可以直接通过命令行管理自己的 MCP 服务配置，类似于 claude mcp：

# Remote servers (Streamable HTTP or SSE)
ollmcp mcp add --transport http <name> <url>
ollmcp mcp add --transport sse <name> <url>

# Local stdio servers - everything after `--` is the command to run
ollmcp mcp add [options] <name> -- <command> [args...]

# List configured servers
ollmcp mcp list

# Remove a server
ollmcp mcp remove <name>

# For more details on options and usage, run:
ollmcp mcp --help
ollmcp mcp add --help

示例：

提示

添加一些服务后，只需运行 ollmcp，它就会自动连接到这些服务。

ollmcp mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer $YOUR_GITHUB_PAT"
ollmcp mcp add --transport stdio playwright npx @playwright/mcp@latest
ollmcp mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /allowed-dir1 ~/allowed-dir2 # stdio transport by default
ollmcp mcp add --env API_KEY=YOUR_KEY --transport sse my-sse-server http://localhost:8000/sse
mcp add 选项
  • --transport、-t：stdio（默认）、sse 或 http。
  • --header、-H：用于 sse/http 服务的 HTTP 标头，格式为 "Name: Value"。可重复指定。
  • --env、-e：用于 stdio 服务的环境变量，格式为 KEY=value。可重复指定。
  • --scope、-s：服务的存储位置（见下方的范围）。默认值：local。
范围
范围加载位置与团队共享存储位置
local仅当前项目否~/.config/ollmcp/mcp.local.json（以项目路径为键）
project仅当前项目是（通过 VCS）项目根目录下的 .mcp.json
user你的所有项目否~/.config/ollmcp/mcp.json

project 范围会在项目根目录写入标准的 .mcp.json 文件，与 Claude Code 及其他支持 MCP 的工具兼容。如果多个范围中存在同名服务，其优先级为 local > project > user。

说明

通过 ollmcp mcp add 添加的服务始终作为基础层加载。任何标志（--mcp-server、--mcp-server-url、--servers-json、--claude-desktop）都会在此基础上添加服务。若要包含 Claude Desktop 中的服务，请明确传入 --claude-desktop。

如果某个服务与通过上述标志之一提供的服务同名，目前会同时打开两个连接，但只有一个会以该名称保持活动状态。请避免在 --mcp-server/--mcp-server-url/--servers-json/--claude-desktop 中重用注册表服务的名称。

命令行参数

提示

CLI 现在使用 Typer，带来更现代的使用体验：分组的选项、丰富的帮助信息，以及内置的 Shell 自动补全。高级用户可以使用短标志来加快命令执行。若要启用自动补全，请运行：

ollmcp --install-completion

然后重启 Shell，或按照打印出的说明操作。

MCP 服务配置：
  • --mcp-server、-s：一个或多个 MCP 服务脚本（.py 或 .js）的路径。可多次指定。
  • --mcp-server-url、-u：一个或多个 SSE 或 Streamable HTTP MCP 服务的 URL。可多次指定。常见端点请参阅常见 MCP 端点路径。
  • --servers-json、-j：包含服务配置的 JSON 文件路径。详情请参阅服务配置格式。
  • --claude-desktop：从 Claude Desktop 的配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）加载服务。与通过 ollmcp mcp add 添加的服务及其他标志合并。

重要

重大变更：--auto-discovery / -a 已替换为 --claude-desktop。此外，通过 ollmcp mcp add 添加的服务现在始终会自动加载，不再是使用其他标志时会消失的后备选项。Claude Desktop 服务不会自动加载；使用 --claude-desktop 将其纳入。

推理提供方配置：
  • --model、-m MODEL：要使用的模型。默认值：如果已设置，则使用已保存配置中的模型；否则使用 Ollama 中的第一个可用模型
  • --provider、-p PROVIDER：要使用的大模型提供方（例如 ollama、openai、atlascloud、openrouter、deepseek）。默认值：ollama
  • --host、-H HOST：大模型主机 / API 基础 URL。对于 ollama 提供方，默认为 Ollama 的 http://localhost:11434；否则默认为该提供方自己的默认端点。
  • --api-key、-k KEY：大模型提供方的 API 密钥。也会从 $OLLMCP_API_KEY 环境变量读取，该变量与提供方无关（适用于通过 --provider 选择的任何提供方）。通过 $OLLMCP_API_KEY 传入的密钥绝不会写入配置文件；只有通过 --api-key 传入的密钥会被保存。ollama 无需密钥。

说明

当前支持的提供方：ollama、openai、atlascloud 以及任何兼容 OpenAI 的提供方（openrouter、deepseek、perplexity 等）。更多提供方即将推出。

通用选项：
  • --version、-v：显示版本并退出
  • --help、-h：显示帮助信息并退出
  • --install-completion：为客户端安装 Shell 自动补全脚本
  • --show-completion：显示可用的 Shell 补全选项
MCP 服务日志：

MCP 服务报告的所有内容都会写入 ~/.config/ollmcp/logs/<session>/<server>.log，每次运行使用一个目录，并保留最近 5 次运行的日志。除非你主动要求，否则服务打印的内容不会显示在屏幕上——否则这些内容会覆盖正在流式传输的回答。

服务通过两个渠道报告信息：其 stderr（仅限 stdio 服务，因为远程服务运行在其他位置）和 MCP 日志通知（适用于任何服务）。这两个标志只会改变屏幕上显示的内容——无论如何，日志文件都会记录所有内容：

写入日志文件显示在屏幕上
(无标志)服务发送的所有内容不显示服务的任何内容
--debug服务发送的所有内容所有内容，实时显示
--log-level LEVEL服务发送的所有内容仅显示 LEVEL 或更高级别的通知
--debug --log-level LEVEL服务发送的所有内容完整 stderr + LEVEL 或更高级别的通知

LEVEL 可以是 debug、info、notice、warning、error、critical、alert 或 emergency。

不使用标志时，完全不会请求日志级别：服务自行决定输出什么，所有内容都会被记录。--log-level 会筛选屏幕上显示的内容，并且在服务声明支持日志记录功能时，也会将该级别发送给服务（logging/setLevel）——此类服务随后可能停止输出较低级别的日志，这些内容也就不会出现在文件中。不支持该功能的服务会继续发送所有内容，并由此处进行筛选。

服务连接失败时，错误信息会指向其日志文件：服务退出前打印的内容都在其中，而这通常就是真正的原因。

说明

ollmcp 自身报告的内容会写入 ~/.config/ollmcp/logs/<session>/ollmcp.log，与服务日志文件放在一起。每次运行都会写入，无需使用 --debug；当响应流提前结束时，屏幕上的警告会指向此文件。目前此功能仍在开发中：日志暂时主要记录提供方和流式传输错误，之后会逐步记录更多内容。

支持的推理提供商

警告

非 Ollama 提供商处于实验阶段。 最近才添加对 Ollama 以外提供商的支持，目前仍在逐步稳定，部分功能可能尚无法正常运行。

ollmcp 支持 Ollama 以及 any-llm 提供的所有 OpenAI 兼容提供商。使用 --provider 进行选择。通过 --api-key 或 $OLLMCP_API_KEY 提供密钥（两者均适用于任何所选提供商），也可以使用下表中对应提供商自己的环境变量。$OLLMCP_API_KEY 和提供商原生环境变量永远不会写入磁盘；只有通过 --api-key 传入的密钥才会保存到配置中。

提供商（--provider）API 密钥环境变量
ollama（默认）-（本地）
atlascloudATLASCLOUD_API_KEY
azureopenaiAZURE_OPENAI_API_KEY
dashscopeDASHSCOPE_API_KEY
databricksDATABRICKS_TOKEN
deepinfraDEEPINFRA_API_KEY
deepseekDEEPSEEK_API_KEY
fireworksFIREWORKS_API_KEY
gatewayGATEWAY_API_KEY
inceptionINCEPTION_API_KEY
llamaLLAMA_API_KEY
llamacpp-（本地）
llamafile-（本地）
lmstudioLM_STUDIO_API_KEY
minimaxMINIMAX_API_KEY
moonshotMOONSHOT_API_KEY
mzaiANY_LLM_KEY
nebiusNEBIUS_API_KEY
openaiOPENAI_API_KEY
openrouterOPENROUTER_API_KEY
perplexityPERPLEXITY_API_KEY
portkeyPORTKEY_API_KEY
qiniuQINIU_API_KEY
sambanovaSAMBANOVA_API_KEY
vllmVLLM_API_KEY
zaiZAI_API_KEY

说明

本地 OpenAI 兼容服务（ollama、llamacpp、llamafile、lmstudio、vllm）通常无需 API 密钥，可通过 --host 指定 ollmcp 连接它们。any-llm 提供的、不兼容 OpenAI 的提供商（例如 anthropic、gemini、mistral、groq、cohere）目前尚不支持。

警告

能力检测限制： ollmcp 只会从 Ollama 读取模型的真实能力（tools、vision、thinking）。对于所有非 Ollama 提供商，目前都假定这三项能力可用，并在模型列表和徽章中如此显示。因此，即使模型实际上不支持工具、视觉或思考，也可能会被报告为支持。如果模型缺少某项能力，尝试使用时提供商的 API 会返回错误。

API 密钥解析顺序

对于选定的提供商，ollmcp 按以下顺序解析 API 密钥，优先级从高到低：

  1. --api-key / -k 标志。
  2. $OLLMCP_API_KEY 环境变量（与提供商无关，适用于你通过 --provider 选择的任何提供商）。
  3. 保存在 ~/.config/ollmcp/config.json 中的该提供商专用密钥（仅当此前通过 --api-key 传入过时才存在）。
  4. 提供商自身的原生环境变量，由 any-llm 检测（例如 OPENAI_API_KEY、OPENROUTER_API_KEY）。

警告

已保存的提供商专用密钥（3）的优先级高于提供商的原生环境变量（4）。因此，如果你之前保存了一个错误或过期的密钥，仅设置 OPENAI_API_KEY（或等效变量）不会覆盖它。要解决此问题，请通过 --api-key 传入正确的密钥，或从 ~/.config/ollmcp/config.json 中该提供商的配置项里删除过时的 apiKey。

使用示例

运行客户端最简单的方法：

ollmcp

提示

这会连接通过 ollmcp mcp add 注册的所有服务，并使用已保存配置文件中的模型；如果没有保存模型，则使用 Ollama 中第一个可用的模型。传入 --claude-desktop 还可包含 Claude Desktop 配置中的服务。

连接到单个服务：

ollmcp --mcp-server /path/to/weather.py --model llama3.2:3b
# Or using short flags:
ollmcp -s /path/to/weather.py -m llama3.2:3b

连接到多个服务：

ollmcp --mcp-server /path/to/weather.py --mcp-server /path/to/filesystem.js
# Or using short flags:
ollmcp -s /path/to/weather.py -s /path/to/filesystem.js

提示

如果未指定 --model，则使用已保存配置文件中的模型；否则会自动选择 Ollama 中第一个可用的模型（如果没有安装模型，系统会告知你如何拉取一个）。

使用 JSON 配置文件：

ollmcp --servers-json /path/to/servers.json --model llama3.2:1b
# Or using short flags:
ollmcp -j /path/to/servers.json -m llama3.2:1b

提示

有关 JSON 文件结构的详细信息，请参阅服务配置格式部分。

使用自定义 Ollama 主机：

ollmcp --host http://localhost:22545 --servers-json /path/to/servers.json
# Or using short flags:
ollmcp -H http://localhost:22545 -j /path/to/servers.json

使用其他大模型提供商（OpenAI 或任何兼容 OpenAI 的 API）：

ollmcp --provider openai --api-key $OPENAI_API_KEY --model gpt-5.5
# OpenAI-compatible providers (e.g. OpenRouter, DeepSeek); override the endpoint with --host if needed:
ollmcp --provider openrouter --api-key $OPENROUTER_API_KEY -m openrouter/free

提示

提供商设置（模型、主机、API 密钥）会按提供商分别记住。通过 /save-config 保存后，直接运行 ollmcp 会恢复上次使用的提供商。详情请参阅配置管理。

通过 URL 连接到 SSE 或 Streamable HTTP 服务：

ollmcp --mcp-server-url http://localhost:8000/sse --model qwen2.5:latest
# Or using short flags:
ollmcp -u http://localhost:8000/sse -m qwen2.5:latest

连接到多个 URL 服务：

ollmcp --mcp-server-url http://localhost:8000/sse --mcp-server-url http://localhost:9000/mcp
# Or using short flags:
ollmcp -u http://localhost:8000/sse -u http://localhost:9000/mcp

混合使用本地脚本和 URL 服务：

ollmcp --mcp-server /path/to/weather.py --mcp-server-url http://localhost:8000/mcp --model qwen3:1.7b
# Or using short flags:
ollmcp -s /path/to/weather.py -u http://localhost:8000/mcp -m qwen3:1.7b

将 Claude Desktop 服务与其他来源的服务一同包含：

ollmcp --mcp-server /path/to/weather.py --mcp-server-url http://localhost:8000/mcp --claude-desktop
# Or using short flags:
ollmcp -s /path/to/weather.py -u http://localhost:8000/mcp --claude-desktop
工具调用的工作方式
  1. 客户端将你的查询和可用工具列表发送给 Ollama
  2. 如果 Ollama 决定使用某个工具，客户端会：
    • 以格式化参数和语法高亮显示工具执行过程
    • 显示人在回路确认提示词（如果已启用），供你查看并批准工具调用
    • 从模型响应中提取工具名称和参数
    • 使用这些参数调用相应的 MCP 服务（仅在获批或禁用 HIL 时）
    • 以结构化、易读的格式显示工具响应（包括图像和不支持媒体的摘要）
    • 如果工具返回了图像且当前模型支持视觉功能，则将图像附加到下一条大模型消息中；否则显示警告
    • 将工具结果发送回 Ollama
    • 如果处于 Agent 模式，则在模型请求更多工具调用时重复此过程
  3. 最后，客户端会：
    • 显示包含工具结果的模型最终响应
Agent 模式

某些模型可能会在一次对话中请求多次工具调用。客户端支持 Agent 模式，允许迭代执行工具：

  • 当模型请求工具调用时，客户端会执行该调用并将结果发送回模型
  • 此过程会重复进行，直到模型给出最终答案或达到配置的循环上限
  • 你可以使用 /loop-limit（/ll）命令设置最大迭代次数
  • 默认循环上限为 7，以防止无限循环
达到循环上限时

客户端不会静默停止，而是暂停并询问你接下来要如何操作：

选项按键说明
继续c (默认)再授予一批迭代次数（与当前上限相同）
指定次数n精确选择还允许多少次迭代
无限制u移除上限，持续运行，直到模型不再请求工具
收尾w让模型总结目前收集到的信息并生成最终答案——保留达到上限前收集到的所有工具结果
中止a完全丢弃本轮操作（不会保存到历史记录）

说明

如果你想阻止使用 Agent Mode，只需将循环上限设为 1。

Agent Mode 快速演示：

asciicast

交互式命令

聊天期间，使用以下命令：

重要

新： 内置交互式命令现在必须以 / 开头。

  • 使用 /help、/model、/tools、/prompts 等。
  • 不再将 help 或 model 这类不带 / 的命令名称作为命令执行。
  • 调用提示词也要使用 /，建议使用 /server:prompt_name 以避免冲突。

ollmcp 主界面

命令快捷方式描述
aborta模型正在生成内容时，中止当前响应的生成
/clear、/new/cc清除对话历史记录和上下文
/cls/clear-screen清除终端屏幕
/context/c切换上下文保留状态
/context-info/ci显示上下文统计信息
/export-history/eh将聊天历史记录导出到 JSON 文件
/full-history/fh显示全部对话历史记录
/help/h显示帮助和可用命令
/import-history/ih从 JSON 文件导入聊天历史记录
/human-in-the-loop/hil切换工具执行的 Human-in-the-Loop 确认
/load-config/lc从文件加载工具和模型配置
/loop-limit/ll设置最大迭代工具循环次数（Agent 模式）。默认值：7
/model/m列出并选择其他 Ollama 模型
/model-config/mc配置高级模型参数和系统提示词
/display-mode/dm选择纯文本、Markdown、两者兼有或 Markdown（代码块）答案显示模式
/input-mode/im选择单行或多行聊天输入模式
/prompts/pr浏览和查看所有可用的 MCP 提示词
/server:prompt_name/prompt_name调用提示词（建议使用限定名称）
/resources/res浏览和查看所有可用的 MCP 资源
@uri-按 URI 读取特定资源（例如，@server://info）
/quit、/exit、/bye/q、Ctrl+C 或 Ctrl+D退出客户端
/reload-servers/rs使用当前配置重新加载所有 MCP 服务
/reset-config/rc将配置重置为默认值（启用所有工具）
/save-config/sc将当前工具和模型配置保存到文件
/show-metrics/sm切换性能指标显示
/show-thinking/st切换思考文本的可见性（默认可见）
/thinking-mode/tm在受支持的模型上切换思考模式
/reasoning-effort/re在思考模式开启时设置推理强度级别（auto/minimal/low/medium/high/xhigh）。默认值：medium
/show-tool-execution/ste切换工具执行信息的显示状态
/tools/t打开工具选择界面
MCP 工具

工具和服务选择界面可让你启用或禁用特定工具：

ollmcp 工具和服务选择界面

  • 输入以逗号分隔的数字（例如 1,3,5）可切换指定工具
  • 输入数字范围（例如 5-8）可切换多个连续工具
  • 输入 S + 数字（例如 S1）可切换特定服务中的所有工具
  • a 或 all - 启用所有工具
  • n 或 none - 禁用所有工具
  • d 或 desc - 显示/隐藏工具说明
  • j 或 json - 显示已启用工具的详细 JSON 架构，以便调试
  • s 或 save - 保存更改并返回聊天
  • q 或 quit - 取消更改并返回聊天
MCP 提示词

MCP 提示词提供由服务定义、可重复使用的对话开场白和上下文模板。服务可以公开带有说明、必需参数和预格式化消息的提示词，帮助你快速开始特定类型的对话，或向聊天中注入结构化上下文。

功能
  • 📋 浏览提示词：查看已连接服务提供的所有可用提示词及其说明和参数要求
  • ⚡️ 快速调用：使用斜杠语法调用提示词（推荐使用 /server:prompt_name）
  • 🔤 自动补全：输入 / 查看提示词建议，并支持模糊匹配
  • 📝 收集参数：交互式提示词会引导你填写必需参数
  • 👁️ 预览：注入前检查提示词内容，确保符合你的需求
  • 🎯 灵活注入：选择立即执行，或仅注入（添加到历史记录但不触发模型）
  • 🧠 感知上下文：根据提示词以用户消息还是助手消息结尾，自动调整行为
  • 🔄 安全回滚：中止操作或遇到错误时，自动清理历史记录
  • 💬 文本内容：支持基于文本的提示词消息（即将支持图像/音频/资源）
如何使用 MCP 提示词

浏览可用提示词：

/prompts  # or '/pr'

此命令会按服务分组显示所有提示词，包括名称、必填参数和描述。

调用提示词：

/server:prompt_name

例如，如果名为 docs 的服务提供了名为“summarize”的提示词：

/docs:summarize

如果某个提示词名称在已连接的服务中唯一，可以使用简写形式：

/summarize

如果多个服务提供了同名提示词，客户端会提示你使用完整形式，并建议有效的 /server:prompt_name 选项。

自动补全：

  • 输入 / 可查看所有可用提示词及其描述
  • 继续输入可通过模糊匹配筛选提示词
  • 使用方向键浏览，然后按 Enter 选择

提示

连接 MCP 服务后，系统会自动发现提示词。如果服务支持提示词，它们会立即显示在 prompts 列表中，也可通过自动补全使用。

工作流：

  1. 输入 /server:prompt_name（推荐），或从自动补全列表中选择
  2. 如果提示词需要参数，系统会提示你提供参数
  3. 查看提示词预览，了解将注入的内容
  4. 选择提示词的使用方式：
    • y/yes（默认）：将提示词发送给模型并获取回复
      • 对于以用户消息结尾的提示词：将该消息用作查询
      • 对于以助手消息结尾的提示词：添加“请根据以上上下文作答。”作为查询
    • i/inject：仅将提示词添加到对话历史中，不触发模型（之后你可以自行输入查询）
    • n/no：取消并返回聊天
  5. 根据你的选择注入提示词
  6. 如果在模型生成过程中中止（按 'a'），更改会自动回滚

示例： ollmcp 提示词功能截图

警告

内容类型限制：MCP 提示词目前仅支持文本内容。以下内容类型尚不支持，将自动跳过：

  • 🖼️ 图像 - 提示词中的图像内容
  • 🎵 音频 - 提示词中的音频内容
  • 📦 资源 - 嵌入的资源内容
MCP 资源

MCP 资源可用于访问 MCP 服务公开的上下文数据，包括文件、文档、结构化数据等。服务可以公开带有元数据（名称、描述、MIME 类型）的资源，供你浏览并读取到对话上下文中。

功能
  • 📋 浏览资源：查看已连接服务中的所有可用资源，包括 URI、名称、MIME 类型和描述
  • 📖 读取资源：使用 @uri 语法读取资源内容，可单独使用，也可嵌入查询中
  • 📝 文本内容：全面支持基于文本的资源（Markdown、代码、日志等）
  • 🖼️ 视觉图像支持：图像资源（image/*）会自动以 base64 图像形式转发给支持视觉功能的模型
  • 🎯 上下文注入：资源内容会被缓冲，并作为上下文与下一条查询一同注入
  • 🔍 自动补全：输入 @ 可通过模糊匹配查看可用资源和模板建议
  • 🛡️ 二进制安全处理：检测到非图像二进制内容（音频、视频、PDF、存档文件）时，会附带说明并安全跳过
如何使用 MCP 资源

浏览可用资源：

/resources  # or '/res'

此命令会按服务列出所有资源和模板，并显示 URI、名称、MIME 类型和描述。二进制资源会标记为 [binary]，模板会标记为 [template]。

读取资源：

@<uri>

例如，读取文件资源：

@file:///path/to/document.md

使用 @uri 有两种方式：

1. 独立使用（先缓冲，再查询）： 单独输入 @uri。资源会被获取并缓冲。然后在下一个提示中输入查询。资源内容会自动注入为上下文。

2. 内联使用（单轮完成）： 在查询文本的任意位置加入 @uri。资源会被获取，查询也会在一个步骤中立即处理。

独立使用示例：

qwen3/show-thinking/6-tools❯ @server://info
✅ Read resource 'get_server_info' (197 chars)

Preview:
This is a simple MCP server with streamable HTTP transport. It supports tools for greeting, adding numbers, generating
random numbers, and calculating BMI. It also provides a BMI calculator prompt.

1 resource(s) buffered. Type your query, or include @another_uri inline.

qwen3/show-thinking/6-tools❯ Next question here

内联使用示例：

qwen3/show-thinking/6-tools❯ summarize the key features from @server://info
✅ Read resource 'get_server_info' (197 chars)

Preview:
This is a simple MCP server with streamable HTTP transport. It supports tools for greeting, adding numbers, generating
random numbers, and calculating BMI. It also provides a BMI calculator prompt.
[model response]

提示

连接到 MCP 服务时会自动发现资源。如果服务支持资源，这些资源会立即出现在 resources 列表和 @ 自动补全中。

说明

🖼️ 支持图像（image/*），图像会以 base64 数据的形式直接传递给支持视觉能力的模型。 二进制内容：以下资源类型不支持作为上下文，会跳过并显示说明性消息：

  • 🎵 音频 - audio/* MIME 类型
  • 📹 视频 - video/* MIME 类型
  • 📄 PDF - application/pdf
  • 🗜️ 压缩文件 - application/zip、application/octet-stream
答案显示模式

/display-mode（/dm）命令可让你选择模型答案在流式输出期间的显示方式：

  • 纯文本：以纯文本形式流式输出响应一次，不进行最终的 Markdown 重新渲染
  • ✨全新 Markdown（默认）：逐行流式输出格式化的 Markdown — 除末尾少量实时输出的行外，上方的行只打印一次，不会重绘，因此即使遇到表情符号或终端尺寸变化，也能保持可靠
  • 两者：先流式输出纯文本，再将完整响应重新渲染为 Markdown
  • Markdown（按块）：一次渲染一个 Markdown 块；采用仅追加方式，每个段落、列表、表格或代码块在完成时打印一次，不会重绘，因此不会重复行

聊天时使用 /display-mode 或 /dm 打开交互式选择器。

切换模式的理由：

  • 如果希望尽量减少重绘或闪烁，纯文本是干扰最少的选项
  • Markdown 将逐行流式输出与连贯的 Markdown 格式结合起来；最多只有最后几行会被重绘，因此即使遇到表情符号或终端尺寸变化，异常也会受到限制
  • 两者既能快速获得流式输出反馈，也能在最后获得整洁的 Markdown 渲染
  • **Markdown（按块）**是在流式输出期间查看格式化 Markdown 最稳妥的方式，代价是按块而非逐行更新

提示

你选择的显示模式会通过 /save-config 保存，并通过 /load-config 恢复，因此可以为不同的工作流保留不同的显示偏好。

输入模式

/input-mode（/im）命令用于控制聊天消息的输入方式：

  • 单行（默认）：输入消息后按 Enter 立即发送
  • 多行：按 Enter 换行，完成后按 Esc 再按 Enter 发送整条消息。这样可以输入包含多个段落或代码块的复杂消息。
  • 多行模式下，Ctrl+J 也可插入换行，作为在各类终端中都可靠的备用方式

聊天时使用 /input-mode 或 /im 打开交互式选择器。

重要

多行发送快捷键可能因终端模拟器和操作系统的键盘处理方式而异。此客户端在多行模式下使用 先按 Esc，再按 Enter 作为通用提交快捷键。某些终端可能支持 Shift+Enter 和 Meta+Enter，但无法保证一定可用。

模型选择

模型选择界面会显示 Ollama 安装中所有可用的模型：

ollmcp 模型选择界面

  • 输入要使用的模型编号
  • s 或 save - 保存模型选择并返回聊天
  • q 或 quit - 取消模型选择并返回聊天
高级模型配置

/model-config (/mc) 命令会打开高级模型设置界面，让你微调模型生成回复的方式：

ollmcp 模型配置界面

系统提示词
  • 系统提示词：设置模型的角色和行为，以引导回复。
关键参数
  • 上下文窗口（num_ctx）：设置模型使用多少聊天历史记录。请平衡上下文长度与内存使用量和性能。
  • 保留令牌数：防止重要令牌被丢弃
  • 最大令牌数：限制回复长度（0 = 自动）
  • 随机种子：使输出可复现（设为 -1 表示随机）
  • 温度：控制随机性（0 = 确定性，值越高越有创造性）
  • Top K / Top P / Min P / Typical P：控制采样多样性
  • 重复次数 / 重复惩罚：减少重复
  • 存在惩罚/频率惩罚：鼓励讨论新主题，减少重复
  • 停止序列：自定义停止点（最多 8 个）
  • 批次大小（num_batch）：控制请求的内部批处理；值越大，吞吐量可能越高，但内存占用也会增加。
命令
  • 输入参数编号 1-15 来编辑设置
  • 输入 sp 来编辑系统提示词
  • 使用 u1、u2 等取消设置参数，或使用 uall 重置全部参数
  • h/help：显示参数详情和提示
  • undo：撤销更改
  • s/save：应用更改
  • q/quit：取消
配置示例
  • 准确求实： temperature: 0.0-0.3、top_p: 0.1-0.5、seed: 42
  • 创意生成： temperature: 1.0+、top_p: 0.95、presence_penalty: 0.2
  • 减少重复： repeat_penalty: 1.1-1.3、presence_penalty: 0.2、frequency_penalty: 0.3
  • 均衡： temperature: 0.7、top_p: 0.9、typical_p: 0.7
  • 可复现： seed: 42、temperature: 0.0
  • 大上下文： 对于需要更多上下文的复杂对话，使用 num_ctx: 8192 或更高值

提示

所有参数默认均未设置，由 Ollama 使用其自身优化后的值。可在配置菜单中使用 help 查看详情和建议。更改会随配置一同保存。

思考模式与推理力度

使用 /thinking-mode (/tm) 启用思考模式，以激活受支持模型的扩展推理（例如 qwen3、deepseek-r1、支持扩展思考的 Claude）。使用 /show-thinking (/st) 切换是否在回复中显示推理过程。

使用 /reasoning-effort (/re) 控制思考模式开启时模型投入多少推理力度：

级别描述
auto提供方的默认力度（推荐用于云端）
minimal速度最快，推理最少
low轻度推理
medium均衡 — 默认
high更深入的推理
xhigh最大推理力度

说明

某些提供方或模型可能会忽略推理力度设置。

开发时重新加载服务

/reload-servers 命令（/rs）在开发 MCP 服务时尤其有用。它可以重新加载所有已连接的服务，而无需重启整个客户端应用程序。

主要优势：

  • 🔄 热重载：立即应用对 MCP 服务代码所做的更改
  • 🛠️ 开发工作流：非常适合迭代开发和测试
  • 📝 配置更新：自动获取服务 JSON 配置或 Claude 配置中的更改
  • 🎯 状态保留：重新加载后保留你对工具启用/禁用状态的偏好
  • ⚡️ 节省时间：无需重启客户端并重新配置所有内容

适用场景：

  • 修改 MCP 服务实现后
  • 更新 JSON 文件中的服务配置后
  • 更改 Claude 的 MCP 配置后
  • 调试时，确保测试的是最新版本的服务

只需在聊天界面中输入 /reload-servers 或 /rs，客户端就会：

  1. 断开与所有当前 MCP 服务的连接
  2. 使用相同参数重新连接（通过 ollmcp mcp add 添加的服务、服务路径、配置文件、--claude-desktop）
  3. 恢复之前的工具启用/禁用设置
  4. 显示更新后的服务和工具状态

此功能可显著改善构建和测试 MCP 服务时的开发体验。

人在回路（HIL）工具执行

人在回路功能提供了额外的安全保障，让你可以在工具执行前进行审核和批准。此功能尤其适用于：

  • 🛡️ 安全性：在执行可能造成破坏的操作前进行审核
  • 🔍 了解情况：了解模型想要使用哪些工具以及原因
  • 🎯 控制：仅执行你批准的工具
  • 🚫 防止误操作：阻止不需要的工具调用执行
  • 🔄 会话模式：自动批准当前查询会话中的所有工具
  • 🛑 中止查询：中止整个查询，且不保存到历史记录
HIL 确认提示

启用 HIL 后，每次执行工具前都会看到确认提示：

示例：

ollmcp HIL 确认截图

HIL 确认选项

出现提示时，你可以选择以下选项：

  • y/yes：执行此工具调用
  • n/no：跳过此工具调用并继续查询
  • s/session：执行此工具调用，以及当前查询中后续的所有工具调用，期间不再提示
  • d/disable：永久禁用 HIL 确认（可使用 /hil 命令重新启用）
  • a/abort：立即中止整个查询，且不保存到历史记录

提示

当模型需要按顺序执行多个工具时，session 选项尤其有用。你无需逐个确认，而是可以批准当前查询会话中的所有工具；HIL 会在下次查询时自动重置。

Human-in-the-Loop（HIL）配置
  • 默认状态：为确保安全，默认启用 HIL 确认
  • 切换命令：使用 /human-in-the-loop 或 /hil 开启或关闭
  • 持久化设置：HIL 偏好设置会随配置一同保存
  • 快速禁用：在任意确认过程中选择“disable”，即可永久关闭
  • 会话自动批准：在确认过程中选择“session”，即可批准当前查询使用的所有工具
  • 中止查询：在确认过程中选择“abort”，即可立即停止查询且不保存
  • 重新启用：随时使用 /hil 命令重新开启确认

优势：

  • 增强安全性：防止意外或不必要的工具执行
  • 了解操作：了解模型尝试执行的操作
  • 选择性控制：逐项选择允许执行的操作
  • 灵活的工作流：使用会话模式高效处理涉及多个工具的查询，对敏感操作单独审批
  • 干净地中止：立即停止有问题的查询，不会污染对话历史
  • 安心无忧：全面了解并控制自动化操作
性能指标

性能指标功能会在每次查询后，在带边框的面板中显示详细的模型性能数据。这些指标直接取自 Ollama 的响应，包括耗时、令牌数和生成速率。

显示的指标：

  • total duration：生成完整响应所用的总时间（秒）
  • load duration：加载模型所用的时间（毫秒）
  • prompt eval count：输入提示词中的令牌数
  • prompt eval duration：评估输入提示词所用的时间（毫秒）
  • eval count：响应中生成的令牌数
  • eval duration：生成响应令牌所用的时间（秒）
  • prompt eval rate：处理输入提示词的速度（令牌/秒）
  • eval rate：生成响应令牌的速度（令牌/秒）

示例： ollmcp ollama 性能指标截图

性能指标配置
  • 默认状态：默认禁用指标，以保持输出简洁
  • 切换命令：使用 /show-metrics 或 /sm 开启或关闭指标显示
  • 持久化设置：指标偏好设置会随配置一同保存

优势：

  • 性能监控：跟踪模型效率和响应时间
  • 令牌跟踪：监控实际令牌消耗，以供分析
  • 性能基准测试：比较不同模型的性能

说明

数据来源：所有指标均直接来自 Ollama 的响应，确保准确可靠。

历史记录管理

历史记录管理功能可让你查看、导出和导入对话历史。适用于以下场景：

  • 📜 查看完整历史记录：回顾当前会话中的所有对话
  • 💾 导出：将对话保存为 JSON 文件，以便备份或分析
  • 📥 导入：加载之前的对话历史，继续之前的内容
  • 🔄 可移植性：在不同会话之间分享或转移对话
历史记录命令

查看完整历史记录：

/full-history  # or '/fh'

以格式化视图显示当前会话中的所有对话历史记录，包括查询和响应。

导出历史记录：

/export-history  # or '/eh'

将当前聊天历史记录导出为 JSON 文件。你可以指定自定义文件名，也可以使用默认的时间戳文件名（例如，ollmcp_chat_history_2026-01-05_143022.json）。文件会保存在 ~/.config/ollmcp/history/ 目录中。此命令会防止覆盖文件。

导入历史记录：

/import-history  # or '/ih'

从 JSON 文件导入之前导出的聊天历史记录。此命令会验证 JSON 结构，确保其兼容性。导入的历史记录会添加到当前对话上下文中。

历史记录存储：

  • 导出位置：~/.config/ollmcp/history/
  • 默认文件名格式：ollmcp_chat_history_YYYY-MM-DD_HHMMSS.json
  • JSON 格式包含查询和响应，并会进行适当的结构验证

优点：

  • 会话连续性：在不同会话之间继续对话
  • 备份：保留重要对话的记录
  • 分析：导出历史记录以供外部分析或审查
  • 共享：与团队成员共享对话上下文
  • 测试：导入测试对话，用于开发和调试

提示

导出时，如果你没有提供文件名，系统会自动生成带时间戳的文件名，以防止意外覆盖。

自动补全和提示词功能

Typer Shell 自动补全
  • CLI 通过 Typer 支持所有选项和参数的 Shell 自动补全
  • 要启用此功能，请运行 ollmcp --install-completion，并按照对应 Shell 的说明操作
  • 通过 Tab 补全所有分组和常规选项
FZF 风格的自动补全
  • 为命令和提示词提供斜杠命名空间自动补全（/）
  • 菜单中显示命令说明
  • 不区分大小写匹配，使用更方便
  • 集中管理命令列表，确保一致性
  • 有意让纯文本查询输入不受操作自动补全干扰
MCP 提示词自动补全
  • 输入 / 以触发提示词自动补全
  • 根据提示词名称和说明进行模糊匹配
  • 支持限定格式的提示词引用，例如 /server:prompt_name
  • 菜单中显示提示词说明
  • 提示词参数会在调用提示词时收集（不会显示在自动补全列表中）
  • 根据终端宽度截断说明
上下文提示符

聊天提示符现在会一目了然地显示清晰的上下文信息：

  • 模型：显示当前使用的 Ollama 模型
  • 思考模式：指示“思考模式”是否已启用（适用于支持该模式的模型）
  • 工具：显示已启用工具的数量

提示符示例：

qwen3/show-thinking/12-tools❯
  • qwen3 模型名称
  • /show-thinking 思考模式指示符（如果已启用；否则显示 /thinking 或不显示）
  • /12-tools 已启用工具的数量（单数时显示 /1-tool）
  • ❯ 提示符号

这样，你在输入查询前就能轻松查看当前上下文。

提示

在提示符号后输入 /，即可查看可用 MCP 提示词的自动补全建议。

配置管理

提示

不带任何标志运行 ollmcp 时，如果默认配置 ~/.config/ollmcp/config.json 存在，系统会自动加载该配置。

客户端会在不同会话之间保存并加载你的偏好设置：

  • 使用 /save-config 时，你可以为配置指定名称，也可以使用默认名称
  • 配置存储在 ~/.config/ollmcp/ 目录中
  • 默认配置保存为 ~/.config/ollmcp/config.json
  • 命名配置保存为 ~/.config/ollmcp/{name}.json
每个提供商的配置文件

连接设置按提供商分别存储，因此切换提供商时绝不会复用其他提供商的模型、主机或 API 密钥。每个提供商都有自己的：

  • 模型选择
  • 主机 / API 基础 URL
  • API 密钥

配置还会记录一个 defaultProvider。运行 ollmcp 且未指定 --provider 标志时，它会加载该提供商的配置文件；全新安装时默认使用 ollama。每次执行 /save-config 时，当前使用的提供商都会成为新的默认提供商，因此直接运行 ollmcp 就会恢复到上次使用的提供商。随时传入 --provider <name>，即可切换到（并加载）其他提供商的配置文件；--model / --host / --api-key 则会覆盖本次运行中保存的值。

说明

只有通过 --api-key 传入的密钥会以纯文本形式存储在 ~/.config/ollmcp/config.json 中。通过 $OLLMCP_API_KEY 环境变量或提供商原生环境变量（例如 OPENROUTER_API_KEY）提供的密钥绝不会写入磁盘；如果不希望密钥被持久保存，请使用其中一种方式。

以下设置会由所有提供商共享：

  • 高级模型参数（系统提示词、温度、采样设置等）
  • 所有工具的启用/禁用状态
  • 上下文保留设置
  • 思考模式设置
  • 答案显示模式偏好
  • 工具执行显示偏好
  • 性能指标显示偏好
  • 人在回路确认设置

~/.config/ollmcp/config.json 示例：

{
  "defaultProvider": "openai",
  "providers": {
    "ollama": { "host": "http://localhost:11434", "model": "qwen3:1.7b", "apiKey": "" },
    "openai": { "host": "", "model": "gpt-5.5", "apiKey": "sk-..." }
  },
  "enabledTools": {},
  "modelConfig": {},
  "...": "shared settings"
}

提示

较旧的扁平配置文件（顶层包含 host/model/provider/apiKey）会在首次运行此版本时自动迁移，并在下次执行 /save-config 时改写为按提供商划分的格式。

服务配置格式

JSON 配置文件支持 STDIO、SSE 和 Streamable HTTP 服务类型（MCP 1.10.1）：

{
  "mcpServers": {
    "stdio-server": {
      "command": "command-to-run",
      "args": ["arg1", "arg2", "..."],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "disabled": false
    },
    "sse-server": {
      "type": "sse",
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer your-token-here"
      },
      "disabled": true
    },
    "http-server": {
      "type": "streamable_http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      },
      "disabled": false
    }
  }
}

说明

MCP 1.10.1 传输支持：客户端现在支持最新的 Streamable HTTP 传输，性能和可靠性均有所提升。如果指定 URL 时未指定类型，客户端默认使用 Streamable HTTP 传输。

提示：MCP 服务配置文件应放在哪里，以及一个可用示例

一个常见的困惑是 MCP 服务配置文件应存放在哪里，以及如何使用 TUI 的保存/加载功能。以下是一份简短实用的指南，希望能帮助其他用户：

  • TUI 的 /save-config / /load-config（或 /sc / /lc）命令用于保存TUI 偏好设置，例如启用了哪些工具、所选模型、思考模式、显示模式以及其他客户端设置。注册 MCP 服务连接不需要使用这些命令。
  • 对于 MCP 服务 JSON 文件（上文所示的 mcpServers 对象），我们建议将其存放在 TUI 配置目录之外，或放在一个清晰的子目录中，例如：
~/.config/ollmcp/mcp-servers/config.json

然后，你可以在启动时通过 -j / --servers-json 将该文件传给 ollmcp。

重要

对于基于 HTTP 的 MCP 服务，"type": "http"、"streamable-http" 和 "streamable_http" 均可接受，且处理方式相同。另请查看下文的常见 MCP 端点路径部分，了解常见端点。

假设这是你的 ~/.config/ollmcp/mcp-servers/config.json，以下是一个可运行的最简示例：

{
  "mcpServers": {
    "github": {
      "type": "streamable_http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer mytoken"
      }
    }
  }
}

提示

使用 GitHub MCP 服务时，请确保将 "mytoken" 替换为你实际的 GitHub API 令牌。

准备好该文件后，你可以使用以下命令连接：

ollmcp -j ~/.config/ollmcp/mcp-servers/config.json

你可以在这里找到一个与此常见问题相关的 GitHub issue：https://github.com/jonigl/mcp-client-for-ollama/issues/112#issuecomment-3446569030

演示

一段简短的演示（asciicast），可帮助任何人快速复现可用配置。此示例使用了一个采用 streamable HTTP 协议的 MCP 服务示例：

asciicast

常见 MCP 端点路径

流式 HTTP MCP 服务通常会将 MCP 端点设为 /mcp（例如，https://host/mcp），而 SSE 服务通常使用 /sse（例如，https://host/sse）。以下摘录自 MCP 规范（2025-06-18）：

服务端 MUST 提供一个同时支持 POST 和 GET 方法的 HTTP 端点路径（下文称为 MCP 端点）。例如，该路径可以是 https://example.com/mcp 这样的 URL。

更多详情请参阅 MCP 规范版本 2025-06-18 - 传输。

说明

远程 MCP 服务的 HTTPS 证书会根据你的操作系统信任存储进行验证，而不是根据 certifi 证书包进行验证。如果 MCP 服务位于私有或企业 CA 后面，或者你在没有系统 CA 存储的精简容器中运行 ollmcp，TLS 握手就会失败，而且错误信息不会提及 ollmcp。将 SSL_CERT_FILE（证书包文件）或 SSL_CERT_DIR（目录）指向你的 CA 即可解决此问题：

export SSL_CERT_FILE=/path/to/corporate-ca.pem

兼容的模型

以下 Ollama 模型适用于工具调用：

  • gemma4
  • qwen3.5
  • lfm2.5-thinking
  • llama3.2
  • mistral

如需查看支持工具调用的完整 Ollama 模型列表，请访问 Ollama 官方模型页面。

如需查看也能处理工具返回图像的模型，请参阅 Ollama 视觉模型页面。

Ollama Cloud 模型

Ollama MCP 客户端现已支持 Ollama Cloud 模型，让你能够使用功能强大的云端托管模型进行工具调用，同时利用本地 MCP 工具。云端模型无需强大的本地 GPU 即可运行，因此你可以使用个人电脑无法容纳的更大型号。

支持的 Ollama Cloud 模型包括：

  • gpt-oss:20b-cloud
  • gpt-oss:120b-cloud
  • deepseek-v3.1:671b-cloud
  • qwen3-coder:480b-cloud

要在此客户端中使用 Ollama Cloud 模型：

  1. 首先，拉取云端模型：

    ollama pull gpt-oss:120b-cloud

  2. 使用所选云端模型运行客户端：

    ollmcp --model gpt-oss:120b-cloud

说明

模型 deepseek-v3.1:671b-cloud 仅在关闭思考模式时支持工具调用。你可以在 ollmcp 中输入 /thinking-mode 或 /tm 来切换思考模式。

如需了解更多 Ollama Cloud 信息，请访问 Ollama Cloud 文档。

赞助商

本项目由以下赞助商支持：

Atlas Cloud

Atlas Cloud

Atlas Cloud 是一个全模态 AI 推理平台——通过统一的 AI API，为视频、图像和大模型工作负载提供对 300 多个精选模型的统一访问。

它开箱即用地兼容 ollmcp：

ollmcp --provider atlascloud --api-key YOUR_ATLASCLOUD_API_KEY
# or export the key once and skip the flag:
export ATLASCLOUD_API_KEY=YOUR_ATLASCLOUD_API_KEY
ollmcp --provider atlascloud

流式传输和工具调用均受支持，你可以通过交互式 /model 命令浏览并选择 Atlas Cloud 的任意模型。

成为赞助商

想让你的 Logo 出现在这里吗？通过 GitHub Sponsors 支持本项目 ❤️

在哪里可以找到更多 MCP 服务？

你可以在官方 MCP 服务仓库中浏览 MCP 服务集合。

该仓库包含模型上下文协议的参考实现、社区构建的服务，以及用于增强大模型工具能力的其他资源。

相关项目

  • Ollama MCP Bridge - 一个位于 Ollama 前端的 Python API 层，可自动将多个 MCP 服务中的工具添加到每个聊天请求中。本项目提供透明的代理解决方案，可在启动时预加载所有 MCP 服务，并将其工具无缝集成到 Ollama API 中。
  • MCP Server with Streamable HTTP Example - 一个 MCP 服务示例，演示如何使用可流式传输的 HTTP 协议。

安全

你连接的 MCP 服务由你信任，其工具和资源的响应会作为不可信内容传递给模型。有关信任模型、如何处理间接提示词注入以及如何报告漏洞，请参阅 SECURITY.md。

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

致谢

  • Ollama 提供本地大模型运行时
  • Model Context Protocol 提供规范和示例
  • any-llm 提供连接多个大模型提供商的统一接口
  • Rich 提供终端用户界面
  • Typer 提供现代化的命令行体验
  • Prompt Toolkit 提供交互式命令行界面
  • uv 提供快速的 Python 包管理器和虚拟环境管理功能
  • Asciinema 提供演示录制

由 jonigl 倾情打造 ❤️

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。