![\"OneTool\"](\"https://raw.githubusercontent.com/beycom/onetool-mcp/main/docs/assets/logo.svg\"){kind=logo}
\n \n\n \n \n \n \n
\n 🧿 One MCP for developers - no tool tax, no context rot.
250+ tools your agent calls as Python code: search, docs, files, databases, diagrams, vision, memory - plus a proxy for every MCP server you already use.\n
\n ![\"PyPI\"](\"https://img.shields.io/pypi/v/onetool-mcp\")
![\"License\"](\"https://img.shields.io/badge/license-GPLv3-blue\"){kind=icon}
![\"Python\"](\"https://img.shields.io/badge/python-3.12%2B-blue\"){kind=icon}
![\"GitHub](\"https://img.shields.io/github/stars/beycom/onetool-mcp\")
\n Works with Claude Code, Cursor, Codex - any MCP client\n
\n\n---\n\n## The Problem\n\nEvery MCP server re-sends its tool definitions on every request: **3K-30K tokens each**. Connect 5 servers and you've burned 55K tokens before the conversation starts. Connect 10+ and you're at 100K.\n\nThe math is brutal: Claude Opus 4.5 at $5/M input tokens, 20 days × 10 conversations × 10 messages × 3K tokens = **$30/month per MCP server** - even if you never use the tools.\n\nAnd then there's **context rot** - your AI literally gets dumber as you add more tools ([Chroma Research, 2025](https://research.trychroma.com/context-rot)).\n\n## The Solution\n\nOneTool is **one MCP server** that exposes tools as a Python API. Instead of reading tool definitions, your agent writes code:\n\n```python\n__onetool brave.search(query=\"react 19 server components\")\n```\n\nConfigure one MCP server. Use unlimited tools - ~2K tokens no matter how many you add.\n\n> \"Agents scale better by writing code to call tools instead. This reduces the token usage from 150,000 tokens to 2,000 tokens...a cost saving of 98.7%\"\n>\n> — [Anthropic Engineering](https://www.anthropic.com/engineering/code-execution-with-mcp)\n\n**97% fewer tokens. 30× lower cost. No context rot.** ([Measured](https://onetool.beycom.online/learn/comparison/) - 47,660 → 1,131 input tokens against 18 MCP servers.)\n\n[📖 Read the full story](https://onetool.beycom.online/about/about-onetool/)\n\n---\n\n## Code Is the Interface\n\nBecause tools are Python functions, your agent does things tool-call JSON can't: batch, chain, loop, compose.\n\n```python\n__onetool\npage = webfetch.fetch(url=\"https://fastmcp.dev/changelog\", output_format=\"markdown\")\nnotes = ot_llm.transform(data=page, prompt=\"Summarise the breaking changes\")\nmem.write(topic=\"deps/fastmcp\", content=notes)\n```\n\nThree packs, one request. Intermediate results flow between tools as variables - the page body never touches your context window, and the summarising runs on a cheap model instead of your expensive coding agent.\n\nEvery call is explicit and reviewable - `__onetool brave.search(query=\"...\")` shows you exactly what runs. No tool-selection guessing.\n\nAnd the runtime is built for how agents actually type:\n\n- `mem.search(q=\"auth\")` works - any unambiguous parameter prefix resolves (`q=` → `query=`)\n- `wb.draw(...)` works - packs have short aliases (`wb`, `ctx`, `img`)\n- `github.listRepositories()` works on proxied servers - snake/camel/Pascal all resolve\n- A typo'd tool gets a did-you-mean, a disconnected server names the command that fixes it\n- Oversized results come back as a searchable handle instead of flooding the window\n\n---\n\n## Install\n\nBootstrap (installs `uv` if missing, installs OneTool, initialises config, prints MCP config):\n\n```bash\ncurl -LsSf https://onetool.beycom.online/install.sh | sh # macOS / Linux\nirm https://onetool.beycom.online/install.ps1 | iex # Windows (PowerShell)\n```\n\nOr install manually with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv tool install 'onetool-mcp[all]' # everything\nonetool init --config ~/.onetool\n```\n\nThen print ready-to-paste MCP client config with resolved absolute paths and add it\nto your client (`claude-code`, `claude-desktop`, `cursor`, or `vscode`):\n\n```bash\nonetool init mcp-config --client claude-code # or omit --client for all four\n```\n\nThat's it. All 250+ tools work out of the box.\n\nVerify: `onetool init validate --config ~/.onetool/onetool.yaml`\n\nInstall the `ot-ref` skill into your agent with [vercel-labs/skills](https://github.com/vercel-labs/skills) - it teaches the call conventions and ships a greppable index of every tool signature:\n\n```bash\nnpx skills add https://github.com/beycom/onetool-mcp --skill ot-ref --agent claude\n```\n\n[📖 Full installation guide](https://onetool.beycom.online/learn/installation/)\n\n---\n\n## What's Inside\n\n| | |\n| --- | --- |\n| **Search & docs** | Brave, Google-grounded, and Tavily search (each with batch + answer modes), Context7 library docs, web fetch with extraction controls |\n| **Files & data** | File ops with path boundaries, full Excel control, SQL databases, PDF/Word/PowerPoint → Markdown, ripgrep, package versions |\n| **Context economy** | `ctx` handles for large outputs, partial file reads (`toc`/`slice`), image vision on a dedicated cheap model (zero host tokens), LLM delegation (10× savings) |\n| **Persistent state** | `mem` memory with semantic + keyword search, history and rollback; `knowledge` RAG bases with AI enrichment; `localhist` Git-backed project snapshots |\n| **Visual** | Live Excalidraw whiteboard with a Mermaid-compatible DSL and offline auto-layout, Mermaid/PlantUML/D2 diagrams, architecture models → draw.io-editable SVG |\n| **Runtime** | MCP server proxy with runtime enable/disable/restart, direct CLI/API into the running process, `ot-ref` agent skill, in-conversation tool forging |\n| **Trust** | age-encrypted secrets backed by your OS keychain, AST validation, path boundaries, output sanitisation, runtime stats with estimated savings |\n\n---\n\n## Tools\n\n28 packs, 253 tools ready to use (`console` in beta):\n\n| Pack | Tools | Extra | Description |\n| ------------- | ------------------------------------------------------------ | -------- | ------------------------------------ |\n| `arch` | `generate`, `validate`, `bundle_solution`, … | `[dev]` | Architecture models → draw.io-editable SVG |\n| `brave` | `search`, `news`, `image`, `video`, `search_batch` | `[util]` | Brave web search |\n| `chrome_util` | `highlight_element`, `guide_user`, … | `[dev]` | Browser annotations (Chrome DevTools) |\n| `console` *(beta)* | `show`, `display`, `list`, `read`, `clear` | | Messages to the upcoming onetool-console app |\n| `context7` | `search`, `doc` | `[dev]` | Library documentation |\n| `convert` | `pdf`, `word`, `powerpoint`, `excel`, `auto` | `[util]` | Documents → Markdown |\n| `db` | `query`, `schema`, `tables`, `sample` | `[dev]` | SQL databases |\n| `diagram` | `render_diagram`, `batch_render`, `get_template`, … | `[dev]` | Mermaid / PlantUML / D2 via Kroki |\n| `excel` | `read`, `write`, `formula`, `create_table`, … (24 tools) | `[util]` | Full Excel control |\n| `file` | `read`, `write`, `edit`, `grep`, `slice`, `toc`, … (16 tools) | `[util]` | File ops with path boundaries |\n| `ground` | `search`, `dev`, `docs`, `reddit`, `search_batch` | `[util]` | Google-grounded search with sources |\n| `knowledge` | `search`, `ask`, `write`, `related`, … (15 tools) | `[util]` | RAG knowledge bases (hybrid search) |\n| `localhist` | `save`, `diff`, `restore`, `autosave_start`, … (15 tools) | `[dev]` | Git-backed local history snapshots |\n| `mem` | `write`, `search`, `ask`, `history`, `rollback`, … (31 tools) | `[util]` | Persistent memory with semantic search |\n| `ot` | `help`, `tools`, `stats`, `status`, `result`, … (18 tools) | | Introspection and management |\n| `ot_context` (`ctx`) | `write`, `read`, `grep`, `slice`, `toc`, `ask`, … (13 tools) | | Smart context store for large outputs |\n| `ot_forge` | `create_ext`, `validate_ext` | | Scaffold new tool packs |\n| `ot_image` (`img`) | `load`, `ask`, `clip_ask`, `summary`, … (9 tools) | | Image vision via a dedicated model |\n| `ot_llm` | `transform`, `transform_file` | | LLM-powered transforms |\n| `ot_secrets` | `set`, `encrypt`, `audit`, `rotate`, … (8 tools) | | Encrypted secrets management |\n| `ot_servers` | `enable`, `disable`, `restart`, `status` | | Runtime control of proxied servers |\n| `ot_timer` | `start`, `stop`, `elapsed`, `list`, `clear` | | Named timers |\n| `package` | `pypi`, `npm`, `version`, `audit`, `models` | `[dev]` | Package versions and staleness |\n| `play_util` | `highlight_element`, `guide_user`, … | `[dev]` | Browser annotations (Playwright) |\n| `ripgrep` | `search`, `count`, `files`, `types` | `[dev]` | Fast code search |\n| `tavily` | `search`, `research`, `extract`, `search_batch`, … | `[util]` | AI-native search and extraction |\n| `webfetch` | `fetch`, `fetch_batch` | `[dev]` | Web content extraction |\n| `whiteboard` (`wb`) | `open`, `draw`, `layout`, `screenshot`, … (22 tools) | `[util]` | Live Excalidraw canvas |\n\n[📖 Complete tools reference](https://onetool.beycom.online/reference/tools/) — every signature, generated from source\n\n---\n\n## MCP Server Proxy\n\nKeep the MCP servers you already use. Wrap them in YAML and call them explicitly - as Python namespaces, without their tool tax:\n\n```yaml\n# .onetool/onetool.yaml\nservers:\n local_tools:\n type: stdio\n command: npx\n args: [\"-y\", \"some-mcp-server@latest\"]\n private_api:\n type: http\n url: ${PRIVATE_MCP_URL}\n auth:\n type: bearer\n token: ${PRIVATE_MCP_TOKEN}\n```\n\n```python\n__onetool private_api.read_resource(path=\"README.md\")\n```\n\nProxied servers can be enabled, disabled, and restarted mid-conversation with `ot_servers` - no client restart.\n\n[📖 Configuration guide](https://onetool.beycom.online/reference/cli/onetool-config/#external-mcp-servers)\n\n---\n\n## Secrets You Can Commit\n\n`onetool init` walks you through encrypted secrets: values in `secrets.yaml` are age-encrypted, the private key lives in your OS keychain, and decryption happens transparently at load.\n\n```yaml\n# secrets.yaml - safe to inspect, safe to commit\nbrave_api_key: age1enc:YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNT...\n```\n\n[📖 Security guide](https://onetool.beycom.online/learn/security/)\n\n---\n\n## Use from the CLI\n\nWorks as an MCP server **and** as a direct CLI bridge into the same running process - loaded config, secrets, and proxy connections stay warm. Useful for agent harnesses, scripts, and automation:\n\n```bash\n# Recommended local MCP root mode: stdio\nonetool serve --config .onetool/onetool.yaml\n\n# URL-based MCP root mode for containerized clients\nonetool serve --transport http --config .onetool/onetool.yaml --host 127.0.0.1 --port 8767 --path /mcp\n\n# Enable the MCP-owned direct API in onetool.yaml:\n# direct.host.enabled: true\n\n# Start OneTool as MCP, then use the port printed in startup logs.\nonetool direct run --port 8765 \"ot.packs()\" --format json | jq '.[0].name'\nonetool direct run --port 8765 \"brave.search(query='latest AI news')\" --format raw\n```\n\n[📖 Direct usage guide](https://onetool.beycom.online/learn/direct-usage/)\n\n---\n\n## Extending\n\nDrop a Python file, get a pack. No registration, no config:\n\n```python\n# .onetool/tools/wiki.py\npack = \"wiki\"\n\ndef summary(*, title: str) -> str:\n \"\"\"Get Wikipedia article summary.\"\"\"\n import httpx\n url = f\"https://en.wikipedia.org/api/rest_v1/page/summary/{title}\"\n return httpx.get(url).json().get(\"extract\", \"Not found\")\n```\n\n```python\n__onetool wiki.summary(title=\"Python_(programming_language)\")\n```\n\n[📖 Creating tools guide](https://onetool.beycom.online/learn/extension-tools/)\n\n---\n\n## Documentation\n\n- [Quickstart](https://onetool.beycom.online/learn/quickstart/) - 30 seconds to first tool call\n- [Installation](https://onetool.beycom.online/learn/installation/) - All platforms\n- [Configuration](https://onetool.beycom.online/learn/configuration/) - YAML schema\n- [Tools Reference](https://onetool.beycom.online/reference/tools/) - All 253 tools\n- [Security](https://onetool.beycom.online/learn/security/) - The layered security model\n- [Extending](https://onetool.beycom.online/learn/extension-tools/) - Build your own\n- [Dev Docs](https://github.com/beycom/onetool-mcp/blob/main/dev/index.md) - Internal developer documentation\n- [Specifications](https://github.com/beycom/onetool-mcp/blob/main/openspec/specs/INDEX.md) - OpenSpec specifications index\n\n---\n\n## References\n\n- [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) - Anthropic Engineering\n- [Context Rot](https://research.trychroma.com/context-rot) - Chroma Research\n\n---\n\n## Telemetry\n\nOneTool sends anonymous startup pings (event type, version, OS). No personal data. Opt out: `export DO_NOT_TRACK=1` or set `telemetry.enabled: false` in `onetool.yaml`. [Details](docs/telemetry.md)\n\n---\n\n## Issues\n\n**Check for existing issues first:**\n\n- Browse the tracker: [github.com/beycom/onetool-mcp/issues](https://github.com/beycom/onetool-mcp/issues)\n- Search with GitHub syntax: `is:issue repo:beycom/onetool-mcp