pi-mcp-adapter
bynicobailon· 1 MCP server
Use MCP servers with Pi without burning your context window.
How to install pi-mcp-adapter?
nicobailon/pi-mcp-adapter
$git clone https://github.com/nicobailon/pi-mcp-adapterInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Install pi-mcp-adapter by running `git clone https://github.com/nicobailon/pi-mcp-adapter`, then use it for the current task and follow its documentation at https://github.com/nicobailon/pi-mcp-adapter.
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 |
Related
6 picksType
- langchain-mcp-adaptersMake Anthropic Model Context Protocol (MCP) tools compatible with LangChain and LangGraph agents.Jul 2026
- mcporterTypeScript runtime and CLI for connecting to configured Model Context Protocol servers.Jul 2026
- mcp-proxyA MCP server which proxies requests to a remote MCP server over streamable HTTP or SSE.Jul 2026
- mcp-atlassianThe Model Context Protocol (MCP) Atlassian integration is an open-source implementation that bridges Atlassian products (Jira and Confluence) with AI language models following Anthropic's MCP specification.Jul 2026
- open-webuiOpen WebUIJul 2026
- rulesyncUnified AI rules management CLI tool that generates configuration files for various AI development toolsJul 2026
