OneTool MCP

🧿 面向开发者的 One MCP——没有工具税，也不会导致上下文腐化。
250 多种工具可供你的 Agent 以 Python 代码调用：搜索、文档、文件、数据库、图表、视觉、记忆——还可代理你已在使用的任何 MCP 服务。

适用于 Claude Code、Cursor、Codex——以及任何 MCP 客户端

---

问题所在

每个 MCP 服务都会在每次请求时重新发送其工具定义：每个定义占用 3K–30K 个 token。连接 5 个服务，在对话开始前就会消耗 55K 个 token。连接 10 个以上，消耗量就达到 100K。

成本高得惊人：以 Claude Opus 4.5 的输入 token 每百万个 5 美元计算，20 天 × 10 次对话 × 每次 10 条消息 × 3K 个 token = 每个 MCP 服务每月 30 美元——即使你从未使用这些工具。

此外还有上下文腐化——工具越多，你的 AI 实际上就越迟钝（Chroma Research，2025）。

解决方案

OneTool 是一个单一 MCP 服务，通过 Python API 提供工具。你的 Agent 无需阅读工具定义，而是编写代码：

__onetool brave.search(query="react 19 server components")

只需配置一个 MCP 服务。工具数量不限——无论添加多少工具，都只需约 2K 个 token。

“让 Agent 通过编写代码来调用工具，能更好地实现扩展。这样可将 token 用量从 150,000 降至 2,000……节省 98.7% 的成本。”

— Anthropic 工程团队

减少 97% 的 token 用量。成本降低 30 倍。不再有上下文腐化。（实测——针对 18 个 MCP 服务，输入 token 从 47,660 降至 1,131。）

📖 阅读完整介绍

---

代码就是接口

由于工具是 Python 函数，你的 Agent 可以执行工具调用 JSON 无法实现的操作：批量调用、串联、循环、组合。

__onetool
page = webfetch.fetch(url="https://fastmcp.dev/changelog", output_format="markdown")
notes = ot_llm.transform(data=page, prompt="Summarise the breaking changes")
mem.write(topic="deps/fastmcp", content=notes)

一次请求，调用三个工具包。中间结果以变量形式在工具间传递——页面正文不会进入你的上下文窗口，而且摘要由低成本模型生成，而非昂贵的编码 Agent。

每次调用都清晰明确、可供审查——__onetool brave.search(query="...") 会准确显示实际执行的操作。无需猜测要选择哪个工具。

运行时也针对 Agent 的实际输入方式进行了优化：

• mem.search(q="auth") 可用——任何无歧义的参数前缀都会被解析（q= → query=）
• wb.draw(...) 可用——工具包提供简短别名（wb、ctx、img）
• 在代理服务上，github.listRepositories() 也可用——snake、camel、Pascal 命名方式均可解析
• 工具名称拼错时会提供相似建议；服务断开连接时会指出修复问题的命令
• 结果过大时会返回可搜索的引用，而不会让窗口被内容淹没

---

安装

引导安装（如果尚未安装，则安装 uv；安装 OneTool、初始化配置并打印 MCP 配置）：

curl -LsSf https://onetool.beycom.online/install.sh | sh          # macOS / Linux
irm https://onetool.beycom.online/install.ps1 | iex               # Windows (PowerShell)

也可以使用 uv 手动安装：

uv tool install 'onetool-mcp[all]'   # everything
onetool init --config ~/.onetool

然后打印可直接粘贴的 MCP 客户端配置，其中包含解析后的绝对路径，并将其添加到你的客户端（claude-code、claude-desktop、cursor 或 vscode）：

onetool init mcp-config --client claude-code   # or omit --client for all four

就这么简单。全部 250 多个工具都可开箱即用。

验证：onetool init validate --config ~/.onetool/onetool.yaml

使用 vercel-labs/skills 将 ot-ref 技能安装到你的 Agent 中——它会讲解调用约定，并附带一个可搜索所有工具签名的索引：

npx skills add https://github.com/beycom/onetool-mcp --skill ot-ref --agent claude

📖 完整安装指南

---

包含内容

搜索与文档	Brave、基于 Google 的搜索和 Tavily 搜索（每种均支持批量和回答模式）、Context7 库文档、带提取控制的网页抓取
文件与数据	带路径边界的文件操作、完整的 Excel 控制、SQL 数据库、PDF/Word/PowerPoint → Markdown、ripgrep、软件包版本
上下文节省	用于处理大型输出的 ctx 句柄、部分读取文件（toc/slice）、使用专用低成本模型进行图像视觉分析（不消耗主机令牌）、LLM 委派（节省 10 倍）
持久状态	支持语义和关键词搜索的 mem 记忆、历史记录与回滚；具备 AI 增强功能的 knowledge RAG 知识库；由 Git 支持的 localhist 项目快照
可视化	实时 Excalidraw 白板，支持 Mermaid 兼容的 DSL 和离线自动布局；Mermaid/PlantUML/D2 图表；可导出为 draw.io 可编辑 SVG 的架构模型
运行时	支持运行时启用/禁用/重启的 MCP 服务代理、直接通过 CLI/API 操作运行中的进程、ot-ref Agent 技能、在对话中即时创建工具
可信性	由操作系统钥匙串保护的 age 加密密钥、AST 验证、路径边界、输出净化、包含预估节省量的运行时统计

---

工具

28 个工具包，共有 253 个工具可供使用（console 仍处于 Beta 阶段）：

Pack	工具	额外	描述
arch	generate, validate, bundle_solution, …	[dev]	架构模型 → 可在 draw.io 中编辑的 SVG
brave	search, news, image, video, search_batch	[util]	Brave 网页搜索
chrome_util	highlight_element, guide_user, …	[dev]	浏览器注释（Chrome DevTools）
console (beta)	show, display, list, read, clear		向即将推出的 onetool-console 应用发送消息
context7	search, doc	[dev]	库文档
convert	pdf, word, powerpoint, excel, auto	[util]	文档 → Markdown
db	query, schema, tables, sample	[dev]	SQL 数据库
diagram	render_diagram, batch_render, get_template, …	[dev]	通过 Kroki 使用 Mermaid / PlantUML / D2
excel	read, write, formula, create_table, … (24 tools)	[util]	完整的 Excel 控制
file	read, write, edit, grep, slice, toc, … (16 tools)	[util]	带路径边界限制的文件操作
ground	search, dev, docs, reddit, search_batch	[util]	基于 Google 并附带来源的搜索
knowledge	search, ask, write, related, … (15 tools)	[util]	RAG 知识库（混合搜索）
localhist	save, diff, restore, autosave_start, … (15 tools)	[dev]	由 Git 支持的本地历史快照
mem	write, search, ask, history, rollback, … (31 tools)	[util]	支持语义搜索的持久化记忆
ot	help, tools, stats, status, result, … (18 tools)		自省与管理
ot_context (ctx)	write, read, grep, slice, toc, ask, … (13 tools)		面向大型输出的智能上下文存储
ot_forge	create_ext, validate_ext		创建新工具包的脚手架
ot_image (img)	load, ask, clip_ask, summary, … (9 tools)		通过专用模型进行图像视觉分析
ot_llm	transform, transform_file		由大模型驱动的转换
ot_secrets	set, encrypt, audit, rotate, … (8 tools)		加密机密管理
ot_servers	enable, disable, restart, status		代理服务的运行时控制
ot_timer	start, stop, elapsed, list, clear		命名计时器
package	pypi, npm, version, audit, models	[dev]	软件包版本与过时情况
play_util	highlight_element, guide_user, …	[dev]	浏览器注释（Playwright）
ripgrep	search, count, files, types	[dev]	快速代码搜索
tavily	search, research, extract, search_batch, …	[util]	面向 AI 的原生搜索与提取
webfetch	fetch, fetch_batch	[dev]	网页内容提取
whiteboard (wb)	open, draw, layout, screenshot, … (22 tools)	[util]	实时 Excalidraw 画布
📖 完整工具参考 — 所有签名均由源代码生成

---

MCP 服务代理

继续使用你已有的 MCP 服务。用 YAML 封装它们，并通过 Python 命名空间显式调用，不产生工具开销：

# .onetool/onetool.yaml
servers:
  local_tools:
    type: stdio
    command: npx
    args: ["-y", "some-mcp-server@latest"]
  private_api:
    type: http
    url: ${PRIVATE_MCP_URL}
    auth:
      type: bearer
      token: ${PRIVATE_MCP_TOKEN}

__onetool private_api.read_resource(path="README.md")

通过代理的服务可在对话中使用 ot_servers 启用、禁用和重启，无需重启客户端。

📖 配置指南

---

可提交的密钥

onetool init 会引导你设置加密密钥：secrets.yaml 中的值会使用 age 加密，私钥存储在操作系统的密钥链中，并在加载时自动解密。

# secrets.yaml - safe to inspect, safe to commit
brave_api_key: age1enc:YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNT...

📖 安全指南

---

从命令行使用

既可用作 MCP 服务，也可作为命令行桥接工具，直接连接到同一运行进程——已加载的配置、密钥和代理连接都会保持就绪。适用于 Agent 执行框架、脚本和自动化：

# Recommended local MCP root mode: stdio
onetool serve --config .onetool/onetool.yaml

# URL-based MCP root mode for containerized clients
onetool serve --transport http --config .onetool/onetool.yaml --host 127.0.0.1 --port 8767 --path /mcp

# Enable the MCP-owned direct API in onetool.yaml:
# direct.host.enabled: true

# Start OneTool as MCP, then use the port printed in startup logs.
onetool direct run --port 8765 "ot.packs()" --format json | jq '.[0].name'
onetool direct run --port 8765 "brave.search(query='latest AI news')" --format raw

📖 直接使用指南

---

扩展

放入一个 Python 文件，即可获得一个工具包。无需注册，无需配置：

# .onetool/tools/wiki.py
pack = "wiki"

def summary(*, title: str) -> str:
    """Get Wikipedia article summary."""
    import httpx
    url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{title}"
    return httpx.get(url).json().get("extract", "Not found")

__onetool wiki.summary(title="Python_(programming_language)")

📖 创建工具指南

---

文档

• 快速入门 - 30 秒即可完成首次工具调用
• 安装 - 支持所有平台
• 配置 - YAML 架构
• 工具参考 - 全部 253 个工具
• 安全 - 分层安全模型
• 扩展 - 构建自己的工具
• 开发文档 - 内部开发文档
• 规范 - OpenSpec 规范索引

---

参考资料

• 使用 MCP 执行代码 - Anthropic Engineering
• 上下文腐化 - Chroma Research

---

遥测

OneTool 会发送匿名启动 ping（事件类型、版本、操作系统），不包含个人数据。选择退出：运行 export DO_NOT_TRACK=1，或在 onetool.yaml 中设置 telemetry.enabled: false。详情

---

问题反馈

请先检查是否已有相关问题：

• 浏览问题跟踪页：github.com/beycom/onetool-mcp/issues
• 使用 GitHub 语法搜索：is:issue repo:beycom/onetool-mcp <keyword>

提交新问题： github.com/beycom/onetool-mcp/issues/new

---

支持

如果你觉得 OneTool 有用：

---

许可证

GPLv3