pi-mcp-adapter
installs/mo · npmstarsforks
How to install pi-mcp-adapter?
nicobailon/pi-mcp-adapter
$git clone https://github.com/nicobailon/pi-mcp-adapterUse MCP servers with Pi without burning your context window.
README.md
| 1 | <p> |
| 2 | <img src="banner.png" alt="pi-mcp-adapter" width="1100"> |
| 3 | </p> |
| 4 | |
| 5 | # Pi MCP Adapter |
| 6 | |
| 7 | Use MCP servers with [Pi](https://github.com/badlogic/pi-mono/) without burning your context window. |
| 8 | |
| 9 | https://github.com/user-attachments/assets/4b7c66ff-e27e-4639-b195-22c3db406a5a |
| 10 | |
| 11 | ## Why This Exists |
| 12 | |
| 13 | Mario wrote about [why you might not need MCP](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/). The problem: tool definitions are verbose. A single MCP server can burn 10k+ tokens, and you're paying that cost whether you use those tools or not. Connect a few servers and you've burned half your context window before the conversation starts. |
| 14 | |
| 15 | His take: skip MCP entirely, write simple CLI tools instead. |
| 16 | |
| 17 | But the MCP ecosystem has useful stuff - databases, browsers, APIs. This adapter gives you access without the bloat. One proxy tool (~200 tokens) instead of hundreds. The agent discovers what it needs on-demand. Servers only start when you actually use them. |
| 18 | |
| 19 | ## Install |
| 20 | |
| 21 | ```bash |
| 22 | pi install npm:pi-mcp-adapter |
| 23 | ``` |
| 24 | |
| 25 | Restart Pi after installation. |
| 26 | |
| 27 | ## What happens on first run |
| 28 | |
| 29 | The adapter reads standard MCP files automatically. No extra setup needed if you already have them. |
| 30 | |
| 31 | | You already have... | What happens | |
| 32 | |---------------------|--------------| |
| 33 | | `.mcp.json` or `~/.config/mcp/mcp.json` | Pi uses it immediately. The first time you open `/mcp`, you'll see a short heads-up explaining which file Pi detected and that Pi only writes adapter-specific overrides to its own files. | |
| 34 | | Host-specific configs (Cursor, Claude Code, Codex, etc.) but no standard MCP files | Run `/mcp setup` to adopt those host configs into Pi. The setup flow shows exactly what it found, lets you pick which ones to import, and previews the exact file changes before writing. | |
| 35 | | Nothing configured yet | Run `/mcp setup` to scaffold a minimal `.mcp.json`, quick-add RepoPrompt, or inspect what the adapter discovered on your machine. | |
| 36 | |
| 37 | If you prefer the terminal, you can also run `pi-mcp-adapter init` after install to scan for host-specific configs and add missing compatibility imports to the Pi agent dir (`~/.pi/agent/mcp.json` by default, or `$PI_CODING_AGENT_DIR/mcp.json` when set). |
| 38 | |
| 39 | ## Quick Start |
| 40 | |
| 41 | Preferred project config: `.mcp.json` |
| 42 | |
| 43 | ```json |
| 44 | { |
| 45 | "mcpServers": { |
| 46 | "chrome-devtools": { |
| 47 | "command": "npx", |
| 48 | "args": ["-y", "chrome-devtools-mcp@latest"] |
| 49 | } |
| 50 | } |
| 51 | } |
| 52 | ``` |
| 53 | |
| 54 | Preferred user-global shared config: `~/.config/mcp/mcp.json` |
| 55 | |
| 56 | Pi also reads Pi-owned override files for settings and host-specific compatibility: |
| 57 | |
| 58 | - `<Pi agent dir>/mcp.json` — Pi global override (`~/.pi/agent/mcp.json` by default) |
| 59 | - `.pi/mcp.json` — Pi project override |
| 60 | |
| 61 | Precedence is: |
| 62 | |
| 63 | 1. `~/.config/mcp/mcp.json` |
| 64 | 2. `<Pi agent dir>/mcp.json` |
| 65 | 3. `.mcp.json` |
| 66 | 4. `.pi/mcp.json` |
| 67 | |
| 68 | Servers are **lazy by default** — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections. |
| 69 | |
| 70 | ``` |
| 71 | mcp({ search: "screenshot" }) |
| 72 | ``` |
| 73 | ``` |
| 74 | chrome_devtools_take_screenshot |
| 75 | Take a screenshot of the page or element. |
| 76 | |
| 77 | Parameters: |
| 78 | format (enum: "png", "jpeg", "webp") [default: "png"] |
| 79 | fullPage (boolean) - Full page instead of viewport |
| 80 | ``` |
| 81 | ``` |
| 82 | mcp({ tool: "chrome_devtools_take_screenshot", args: '{"format": "png"}' }) |
| 83 | ``` |
| 84 | |
| 85 | Note: `args` is a JSON string, not an object. |
| 86 | |
| 87 | Two calls instead of 26 tools cluttering the context. |
| 88 | |
| 89 | ## Config |
| 90 | |
| 91 | ### File Layout |
| 92 | |
| 93 | Use the shared MCP files when you want one setup to work across hosts, and Pi-owned files when you need Pi-specific overrides or settings. |
| 94 | |
| 95 | | File | Purpose | |
| 96 | |------|---------| |
| 97 | | `~/.config/mcp/mcp.json` | User-global shared MCP config | |
| 98 | | `.mcp.json` | Project-local shared MCP config | |
| 99 | | `<Pi agent dir>/mcp.json` | Pi global override and compatibility imports (`~/.pi/agent/mcp.json` by default) | |
| 100 | | `.pi/mcp.json` | Pi project override | |
| 101 | |
| 102 | Pi-specific files are the write targets for imported or shared global servers when Pi needs to persist adapter-only settings such |
People who liked this also viewed
6 picksType
- fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!MCP ServersNov 2025
- lean-lsp-mcpLean Theorem Prover MCPMCP ServersJul 2026
- rulesyncA Utility CLI for AI Coding AgentsMCP ServersJul 2026
- FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.MCP ServersJul 2026
- repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.MCP ServersJul 2026
- mcp-serverMCP server for AI-assisted development of CAP applicationsMCP ServersJul 2026
