pi-mcp-adapter: MCP-Server in Pi nutzen, ohne das Kontextfenster zu füllen
Token-efficient MCP adapter for Pi coding agent
Auf einen Blick
- Was ist das?
- Der Adapter ersetzt Dutzende MCP-Tool-Definitionen durch ein einziges Proxy-Tool von rund 200 Token. Er lohnt sich für Pi-Nutzer mit mehreren MCP-Servern und ist für alle anderen überflüssig.
- Für wen ist es gedacht?
- Wer Pi mit mehreren MCP-Servern betreibt und wiederkehrend Kontextfenster durch ungenutzte Tool-Definitionen verliert, sollte den Adapter installieren und zuerst mit /mcp setup prüfen, welche Host-Konfigurationen er findet und importieren will. Wer MCP grundsätzlich meidet oder nur einen einzigen Server mit wenigen Tools anbindet, gewinnt durch das Proxy-Tool kaum etwas und trägt zusätzlich eine Zwischenschicht in den Aufrufpfad ein.
- Darf ich es kommerziell nutzen?
- Ja. MIT ist eine freizügige Lizenz: Sie dürfen darauf aufbauende Software nutzen, verändern und verkaufen, solange Sie die Urheberrechts- und Lizenzhinweise beibehalten.
- Wird es noch gepflegt?
- Ja. Die letzten Commits kamen vor 1 Tag.
- In welcher Sprache ist es geschrieben?
- Hauptsächlich TypeScript, laut der Sprachstatistik von GitHub.
Die Antworten beruhen auf den GitHub-Daten des Projekts (zuletzt abgeglichen am 15. September 2026) und auf unserer Analyse. Sie sind keine Rechtsberatung.
TIEFGEHENDE OPEN-SOURCE-ANALYSE
Das Problem sind die Tool-Definitionen, nicht die Server
MCP-Server liefern nützliche Fähigkeiten: Datenbanken, Browser-Steuerung, APIs. Der Preis dafür steht im Kontextfenster. Das README nennt eine Größenordnung von über 10k Token für einen einzelnen Server, und diese Kosten fallen an, egal ob ein Tool in der Sitzung jemals aufgerufen wird. Bei mehreren verbundenen Servern ist ein erheblicher Teil des Kontexts belegt, bevor das erste Gespräch beginnt.
Der Adapter setzt genau dort an. Statt hunderter Tool-Definitionen registriert er ein einziges Proxy-Tool, das laut README etwa 200 Token belegt. Das ist kein Werkzeug für Leute, die MCP ohnehin ablehnen, sondern für diejenigen, die es nutzen wollen und die Rechnung dafür nicht mit Kontext bezahlen möchten. Die Zielgruppe ist damit klar umrissen: Pi-Nutzer mit mehreren konfigurierten MCP-Servern.
Ein Proxy-Tool statt 26 registrierter Werkzeuge
Der Mechanismus ist eine Indirektion über zwei Aufrufe. Zuerst wird gesucht, dann ausgeführt. Das README zeigt beide Schritte. Der Suchaufruf lautet mcp({ search: "screenshot" }) und liefert eine Beschreibung des passenden Tools samt Parametern, im Beispiel chrome_devtools_take_screenshot mit den Feldern format und fullPage. Der zweite Aufruf führt es aus: mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } }).
Das Argument args akzeptiert laut README sowohl ein JSON-Objekt als auch einen JSON-String. Die Objektform wird empfohlen, wenn das Modell sie zuverlässig verarbeitet; die Stringform bleibt für Provider erhalten, die einfachere Schemata benötigen. Das ist ein Zugeständnis an die Realität unterschiedlicher Modell-Provider und kein Schönheitsfehler.
Die Server selbst sind standardmäßig lazy. Sie verbinden sich erst, wenn tatsächlich eines ihrer Tools aufgerufen wird. Damit Suche und Beschreibung auch ohne laufende Verbindung funktionieren, cached der Adapter die Tool-Metadaten. Dieser Cache ist die Voraussetzung dafür, dass der Suchschritt überhaupt ohne Serverkontakt auskommt. Wer viele Server konfiguriert hat, aber in einer Sitzung nur einen davon braucht, zahlt für die übrigen nur den Cache-Eintrag, nicht die Verbindung.
Installation und der erste Lauf mit /mcp setup
Die Installation erfolgt über den Pi-Paketmanager: pi install npm:pi-mcp-adapter. Danach muss Pi neu gestartet werden, damit die Erweiterung greift.
Für den ersten Lauf beschreibt das README drei Ausgangslagen. Wer bereits .mcp.json oder ~/.config/mcp/mcp.json besitzt, wird sofort bedient; beim ersten Öffnen von /mcp erscheint ein Hinweis, welche Datei erkannt wurde und dass Pi nur adaptereigene Overrides in eigene Dateien schreibt. Wer Host-Konfigurationen von Cursor, Claude Code oder Codex hat, aber keine standardkonformen MCP-Dateien, ruft /mcp setup auf. Der Ablauf zeigt, was gefunden wurde, lässt auswählen, was importiert wird, und stellt die Dateiänderungen vor der Ausführung dar. Wer noch nichts konfiguriert hat, wählt im Setup zwischen einem Projekt-.mcp.json und einer globalen ~/.config/mcp/mcp.json und legt dann eine minimale Konfiguration an.
Für die Kommandozeile gibt es pi-mcp-adapter init. Der Befehl durchsucht das System nach hostspezifischen Konfigurationen und ergänzt fehlende Kompatibilitätsimporte im Pi-Agent-Verzeichnis, standardmäßig ~/.pi/agent/mcp.json oder $PI_CODING_AGENT_DIR/mcp.json, wenn diese Variable gesetzt ist.
Sechs Konfigurationsquellen mit fester Rangfolge
Der Adapter liest nicht eine Datei, sondern mehrere, und die Reihenfolge entscheidet. Das README listet sechs Ebenen, wobei spätere Einträge frühere überschreiben: ~/.config/mcp/mcp.json, dann ~/.agents/mcp.json, dann ~/.agents/mcp/mcp.json, dann das Pi-Agent-Verzeichnis mcp.json, dann das projektlokale .mcp.json und zuletzt .pi/mcp.json.
Diese Rangfolge ist der Grund, warum /mcp disable <server> und /mcp enable <server> funktionieren, ohne fremde Dateien anzufassen. Beide Befehle schreiben ausschließlich das Feld disabled in die projektlokale .pi/mcp.json, die oberste Pi-Ebene. Beim Aktivieren entfernt der Adapter das Projektflag, wenn untere Ebenen bereits aktiv sind, oder schreibt false, wenn eine deaktivierte untere Quelle überschrieben werden muss. Die Quelldatei wird dabei nie umgeschrieben, und Zugangsdaten werden nie kopiert. Nach einer Änderung des Flags ist /reload nötig, damit die registrierten Tool-Oberflächen aktualisiert werden.
Ein Sonderfall ist im README ausdrücklich vermerkt: Konfigurationen, die speicherintern über createMcpAdapter({ config }) übergeben werden, sind isoliert und lesen oder schreiben diese Projekt-Override nicht. In diesem Modus stehen die Befehle nicht zur Verfügung. Wer den Adapter programmatisch einbettet, verliert also die Bequemlichkeit der Enable- und Disable-Befehle.
Host-Konfigurationen werden nicht automatisch geladen
Hier weicht der Adapter von dem ab, was man erwarten könnte. Hostspezifische Konfigurationen von Cursor, Claude Code oder Codex werden zwar erkannt und angezeigt, sind aber ausdrücklich Kompatibilitätseingaben und keine normalen Einrichtungspfade. Automatisch geladen werden sie nicht. Das normale /mcp-Panel durchsucht hostspezifische Dateien erst gar nicht, solange settings.hostConfigDiscovery auf "off" steht, und das ist der Standardwert.
Wer die Erkennung will, muss sie explizit einschalten, entweder über settings.hostConfigDiscovery auf "on" oder über pi-mcp-adapter init --discover-host-configs. Ein dritter Wert "prompt" ist für Integrationen gedacht, die Erkennung ohne Aktivierung wünschen. Auch wenn die Erkennung läuft, bleiben Host-Konfigurationen in der Rangfolge unter allen geteilten und Pi-eigenen Quellen. Der Bericht umfasst Quellpfade, Herkunft und Namenskonflikte; in externe Host-Dateien wird nie geschrieben, und aus ihnen werden nie stillschweigend Kommandos gestartet. Diese Voreinstellung ist bewusst defensiv und dürfte für alle richtig sein, die nicht genau wissen, welche Host-Konfigurationen auf ihrem Rechner liegen.
Agent Plugins und der Preis der Zwischenschicht
Neben den JSON-Dateien kann der Adapter Server aus Agent-Plugins-Paketen laden. Dazu wird settings.agentPluginPaths eine Liste von Verzeichnissen übergeben, und jedes Verzeichnis muss eine gültige plugin.json nach Agent Plugins 1.0 enthalten. Das README bricht an dieser Stelle ab, weitere Bedingungen für das Laden nennt das vorliegende Material nicht.
Die eigentliche Einschränkung liegt im Entwurf selbst. Jeder Tool-Aufruf wird zu zwei Aufrufen: erst suchen, dann ausführen. Bei einem einzelnen Server mit wenigen Tools ist das ein zusätzlicher Modellschritt ohne Gegenwert, denn das Kontextproblem, das der Adapter löst, existiert dort gar nicht. Wer MCP ohnehin meidet und stattdessen kleine CLI-Werkzeuge schreibt, ist ebenfalls nicht die Zielgruppe; der Adapter setzt MCP voraus und macht es nur billiger.
Dazu kommt die Abhängigkeit von den gecachten Metadaten. Suche und Beschreibung arbeiten laut README ohne laufende Verbindung, was bedeutet, dass der Cache den Stand bestimmt. Ändert ein Server seine Parameter, ohne dass der Cache aktualisiert wird, beschreibt die Suche womöglich ein veraltetes Schema. Das Material sagt nichts darüber, wann oder wie der Cache invalidiert wird. Diese Frage sollte man klären, bevor man den Adapter auf Server mit häufig wechselnden Schnittstellen richtet.
Alternative: CLI-Werkzeuge statt MCP-Proxy
Die im README referenzierte Alternative ist der Verzicht auf MCP zugunsten einfacher CLI-Werkzeuge. Der Unterschied liegt nicht im Tokenverbrauch, sondern in der Struktur. Ein CLI-Werkzeug ist ein Kommando, das der Agent direkt aufruft; es gibt keine Tool-Definition, keinen Metadaten-Cache, keine Verbindung, die verwaltet werden muss. Dafür muss jedes Werkzeug von Hand geschrieben und gepflegt werden, und es erscheint nicht in der automatischen Tool-Suche des Adapters.
Der Kompromiss ist damit klar: Der Adapter kauft Bequemlichkeit und Zugang zum bestehenden MCP-Ökosystem gegen einen zusätzlichen Suchschritt und eine Zwischenschicht ein. Ein handgeschriebenes CLI-Werkzeug kauft maximale Schlankheit gegen manuelle Arbeit pro Werkzeug. Für ein einzelnes, selten genutztes Kommando ist das Skript gewonnen. Für einen Browser mit Dutzenden Aktionen ist der Proxy-Aufruf die günstigere Variante.
Lizenz, Pflege und was vor dem Ausrollen zu prüfen ist
Der Code steht unter MIT. Das erlaubt kommerzielle Nutzung und Modifikation, verlangt aber, den Lizenztext und den Urheberrechtshinweis beizubehalten. Wer den Adapter forkt und intern weiterverteilt, muss diese Bedingung einhalten. Rechtliche Beratung ersetzt das nicht.
Zur Pflege lässt sich aus dem Material nur wenig Sicheres ableiten. Der letzte Push liegt auf dem 5. September 2026, die jüngste Veröffentlichung v2.32.1 auf dem 1. September 2026, davor v2.32.0 am selben Tag und v2.31.0 am 28. August 2026. Die Versionsnummern im 2.3x-Bereich und die kurzen Abstände deuten auf häufige Korrekturen hin. Ob das auf eine stabile Schnittstelle schließen lässt, ist damit nicht belegt.
Konkret zu prüfen sind drei Punkte. Erstens, ob der Metadaten-Cache aktualisiert wird, wenn ein Server seine Parameter ändert. Zweitens, ob das Projekt .mcp.json versioniert und geteilt wird oder ob die Pi-Overrides in .pi/mcp.json bleiben und die gemeinsame Basis über ~/.config/mcp/mcp.json läuft, denn die Rangfolge entscheidet, welche Datei im Konfliktfall gewinnt. Drittens, ob der Adapter nach jeder Änderung an einem disabled-Flag tatsächlich per /reload die Tool-Oberflächen neu aufbaut, wie das README es verlangt.
Redaktionelles Fazit
Wer Pi mit mehreren MCP-Servern betreibt und wiederkehrend Kontextfenster durch ungenutzte Tool-Definitionen verliert, sollte den Adapter installieren und zuerst mit /mcp setup prüfen, welche Host-Konfigurationen er findet und importieren will. Wer MCP grundsätzlich meidet oder nur einen einzigen Server mit wenigen Tools anbindet, gewinnt durch das Proxy-Tool kaum etwas und trägt zusätzlich eine Zwischenschicht in den Aufrufpfad ein. Vor dem Ausrollen im Team ist zu klären, ob .mcp.json gemeinsam versioniert wird oder ob die Pi-eigenen Overrides in .pi/mcp.json bleiben und der Rest über ~/.config/mcp/mcp.json läuft.
Community-Notizen