Local Agent MCP

English · Berechtigungshinweise · Architektur

Lass ChatGPT Pro direkt auf deinem lokalen Computer arbeiten

Du gibst ChatGPT einen Auftrag, und es kann lokale MCP-Tools aufrufen: Projekte lesen, Dateien ändern, Tests ausführen, Git-Diff prüfen, Commits erstellen.

Komplexe Aufgaben kannst du an lokales Codex übergeben. ChatGPT übernimmt weiterhin das Aufteilen in Schritte, das Prüfen des Fortschritts, das Ergänzen von Anforderungen und die abschließende Kontrolle.

ChatGPT Pro
→ Local Agent MCP
→ 本地文件 / 测试 / Git / Codex

Kein wiederholtes Kopieren von Code, und nicht jede Aufgabe muss über Codex laufen.

Dies ist ein inoffizielles Community-Projekt. Es ist kein OpenAI-Produkt und steht nicht für OpenAI.

Related MCP server: chatgpt-codex-tools-mcp

Schnellstart

Voraussetzungen

Halte Folgendes bereit:

• macOS oder Linux

• Python 3.11 oder höher

• Git

• uv

• Offizielles tunnel-client von OpenAI

• Eine ChatGPT-Umgebung, die benutzerdefinierte MCP-Apps unterstützt

• Eine Tunnel-ID

• Einen passenden Tunnel-Runtime-Key

Auf macOS kannst du zuerst die Basistools installieren:

brew install uv tmux
brew install openai/tools/tunnel-client

In einem Satz an die KI übergeben

Sende diesen Satz an eine KI, die ein lokales Terminal bedienen kann:

Installiere https://github.com/ezra-y/local-agent-mcp auf meinem Computer und führe die Konfiguration, den Start und die Verifizierung gemäß der README durch.

Manuelle Installation siehe: Installation in ChatGPT.

Highlights

28 Tools

Ein direktes delete_file-Tool ist nicht verfügbar. apply_patch lehnt außerdem das Löschen ganzer Dateien ab.

git_commit deaktiviert standardmäßig Repository-Hooks und Commit-Signaturen. Wenn clean- / process-Git-Filter erkannt werden, wird der Commit abgelehnt, damit strukturierte Commits nicht implizit Repository-Programme ausführen. git_diff deaktiviert gleichzeitig externe Diffs und textconv.

Berechtigungs-Resource

Neben dem get_permissions-Tool stellt der Dienst außerdem bereit:

local-agent://permissions

Der Inhalt umfasst:

当前允许访问哪里
哪些目录和文件被禁止
读写是否开启
有没有直接删除工具
高权限入口有哪些

get_permissions bleibt erhalten, damit Clients, die MCP-Resources noch nicht anzeigen, es weiterhin nutzen können.

Berechtigungen und Rechteeinschränkung

Standardbereich

Strukturierte Datei- und Git-Tools können standardmäßig auf das Home-Verzeichnis des aktuellen Benutzers zugreifen:

$HOME

Das umfasst in der Regel Desktop, Downloads, Documents und andere Projekte in persönlichen Verzeichnissen.

Vom Code hart verbotene Inhalte

Strukturierte Datei-Tools lehnen Folgendes ab:

.ssh
.aws
.azure
.codex
.docker
.gnupg
.kube
.Trash
Library
.env 和 .env.*
常见凭据文件
.pem / .key / .p12 / .pfx 私钥文件
符号链接路径

Außerdem:

• Es gibt kein direktes Dateilösch-Tool.

• apply_patch kann keine ganze Datei löschen.

• Es gibt kein Git-Push-Tool.

• git_commit committet nur explizit gelistete Pfade.

Strukturierten Bereich einschränken

Vor dem Start festlegen:

export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"

Der alte Konfigurationsname CODEX_MCP_ROOT bleibt kompatibel.

Danach können diese Tools nur noch auf $HOME/Projects zugreifen:

list_files
read_file
write_file
apply_patch
git_status
git_diff
git_commit

Beispiel für den Start im Vordergrund:

export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"
./scripts/run_tunnel.sh

Einstiegspunkte mit hohen Rechten

LOCAL_AGENT_MCP_ROOT ist die harte Grenze für strukturierte Datei- und Git-Tools, nicht eine System-Sandbox für den gesamten Prozess.

Wenn Repository-Hooks, Git LFS oder andere Filter benötigt werden, committe bitte manuell oder verwende das hochprivilegierte run_command, nachdem du die Repository-Konfiguration ausdrücklich geprüft hast.

v0.5.1 bietet derzeit keine Konfiguration zum Ausblenden oder Deaktivieren einzelner Tools. Für stärkere Isolation kannst du einen separaten Systembenutzer, eine VM, einen Container oder eine Version mit reduzierten Tools verwenden.

Vollständige Hinweise siehe docs/permissions.md.

Installation in ChatGPT

1. Herunterladen und testen

git clone https://github.com/ezra-y/local-agent-mcp.git
cd local-agent-mcp
uv sync --locked --all-groups
uv run pytest -q

Die Suchreihenfolge für lokales Codex:

1. Pfad, der über CODEX_BIN angegeben ist.

2. codex in PATH.

3. Das in der macOS-ChatGPT-App integrierte Codex.

2. Runtime-Key speichern

macOS:

./scripts/save_tunnel_key.sh

Linux:

export CONTROL_PLANE_API_KEY="<你的 Runtime Key>"

3. Tunnel-Konfiguration erzeugen

export CONTROL_PLANE_TUNNEL_ID="tunnel_<32位小写十六进制>"
./scripts/configure_tunnel.sh

Die lokale Konfiguration wird gespeichert unter:

.runtime/profiles/

4. Tunnel starten

Vordergrund:

./scripts/run_tunnel.sh

Hintergrund:

tmux new-session -d \
  -s local-agent-mcp-tunnel \
  -c "$PWD" \
  ./scripts/run_tunnel.sh

Auf die Bereitschaft des Dienstes warten:

for i in {1..30}; do
  curl -fsS http://127.0.0.1:8741/readyz && break
  sleep 1
done

Bei Erfolg wird zurückgegeben:

ready

Lokale Statusseite:

http://127.0.0.1:8741/ui

5. In ChatGPT verbinden

1. Öffne Einstellungen → Apps.

2. Aktiviere den Entwicklermodus.

3. Erstelle oder verbinde die entsprechende benutzerdefinierte MCP-App.

4. Klicke nach dem Start des Tunnels auf Refresh / Scan tools.

5. Öffne einen neuen Chat und wähle @Local Agent.

6. Verifizieren

Sende in einem neuen Chat:

@Local Agent

调用 get_permissions。
报告当前工具总数、版本和 allowed_root。

Erwartetes Ergebnis für v0.5.1:

工具总数：28
版本：0.5.1
allowed_root：你的 Home，或你设置的 LOCAL_AGENT_MCP_ROOT

Wenn der Client Resources unterstützt, versuche zusätzlich zu lesen:

local-agent://permissions

Nur lokales stdio-MCP ausführen

Ohne ChatGPT-Tunnel:

./scripts/run_mcp.sh

Du kannst es auch als globalen Befehl installieren:

uv tool install .
local-agent-mcp

Der alte Befehl local-codex-mcp bleibt weiterhin verfügbar.

Tägliche Nutzung

Der Parameter project in den Tools wird in der Regel als Pfad relativ zu $HOME angegeben:

Documents/Codex/local-agent-mcp
Downloads/my-project
Desktop/example-project

Absolute Pfade innerhalb des Home-Verzeichnisses werden ebenfalls unterstützt. project="." steht für das gesamte strukturierte Stammverzeichnis; in der Standardeinstellung ist das das gesamte Home-Verzeichnis.

Eine häufige Aufgabe

@Local Agent

在 Downloads/my-project 修复登录失败问题。
检查相关代码和 Git 状态，完成修改、测试、Diff 和 Commit。

Häufiger Ablauf:

get_permissions
→ git_status / list_files / read_file
→ write_file / apply_patch
→ run_tests
→ git_diff
→ git_commit

Bei komplexen Aufgaben kannst du zusätzlich einen expliziten Workflow oder lokales Codex einbinden.

Wie Workflows ablaufen

Fünf Konzepte

Ausführungsreihenfolge

create_workflow
→ create_step
→ start_step
→ get_job / get_workflow

create_step unterstützt derzeit vier Ausführungstypen:

Dateilesen und -ändern erfolgen weiterhin direkt über read_file, write_file und apply_patch.

Beispiel: Test-Step erstellen

create_workflow(
  project="Downloads/my-project",
  title="验证登录修复"
)
→ workflow_id

create_step(
  workflow_id=workflow_id,
  position=1,
  name="运行测试",
  executor_kind="tests",
  spec={
    "argv": ["uv", "run", "pytest", "-q"],
    "cwd": ".",
    "timeout_seconds": 900
  },
  write_scope="worktree"
)
→ step_id

start_step(
  workflow_id=workflow_id,
  step_id=step_id,
  attempt=1
)
→ job_id

get_job(job_id)
get_workflow(workflow_id)

Die Ausführungsidentität ist:

workflow_id + step_id + attempt

Ein erneuter Start mit derselben Nummer gibt den ursprünglichen Job zurück und führt nicht doppelt aus. Für eine ausdrückliche Wiederholung verwende eine neue attempt, z. B. attempt=2.

Parallelitätsregeln

同一个 Codex Thread：同一时间一个活动 Turn
同一个 Worktree：同一时间一个写入者
同一个仓库：不同 Worktree 可以并行

Wenn ein aktiver Turn zusätzliche Anforderungen benötigt, verwende steer_codex_turn; zum Stoppen verwende interrupt_codex_turn.

Lokaler Status und Logs

Beim Ausführen aus dem Quellcode:

.runtime/state.sqlite3
.runtime/artifacts/<job_id>/

Der installierte Befehl verwendet standardmäßig:

$HOME/.local/state/local-agent-mcp/state.sqlite3

Benutzerdefinierter Speicherort:

export LOCAL_AGENT_MCP_STATE_PATH="/自定义位置/state.sqlite3"

Der alte Konfigurationsname CODEX_WORKFLOW_STATE_PATH bleibt kompatibel. Vorhandene alte Statusdatenbanken werden weiterhin gelesen.

Lange Logs werden in Artifact-Dateien abgelegt. SQLite speichert Pfad, Größe und SHA-256.

Artifacts werden nicht automatisch gelöscht. Wenn die Gesamtmenge 1 GiB überschreitet, gibt ping eine Warnung zurück.

Aktualisierung

git pull
uv sync --locked --all-groups
uv run pytest -q

Danach den Tunnel neu starten und in ChatGPT auf Refresh / Scan tools klicken.

Projektstruktur

src/local_agent_mcp/
├── server.py                 MCP 入口与公共 Tool / Resource
├── adapters/                 本地 Agent Adapter；当前包含 Codex
├── workflow_*.py             Workflow、Step、Job、锁和 SQLite
├── command_jobs.py           后台命令与测试
├── workspace_tools.py        文件读写与 Patch
└── git_tools.py              Git 状态、Diff 和 Commit

tests/                        单元测试与集成测试
docs/                         权限和架构说明
scripts/                      MCP 与 Tunnel 启动脚本

Testdateien bleiben im Repository. Sie dienen der Verifizierung von Berechtigungsgrenzen, plattformübergreifendem Betrieb, Paketierung und Kompatibilität; das installierte Wheel enthält nur den ausführenden Code.

Entwicklungsprüfungen

uv run pytest -q
uv run python scripts/check_public_release.py
zsh -n scripts/*.sh
uv build

Der Haupt-MCP-Einstiegspunkt ist src/local_agent_mcp/server.py. src/codex_bridge.py bleibt als kompatibler Alias für alte Importe und alte Startmethoden erhalten.

Deinstallation und lokale Daten

Das Deinstallationsprogramm löscht SQLite, Artifacts, Tunnel-Profile oder das Quellverzeichnis nicht automatisch. Bitte prüfe zuerst und entscheide, welche Daten du behalten möchtest.

Lizenz

MIT, siehe LICENSE.

⚠️ Die Standardkonfiguration gewährt umfangreiche lokale Berechtigungen: ChatGPT kann die meisten Projekte im Home-Verzeichnis des aktuellen Benutzers lesen und beschreiben sowie Tests, Befehle und lokale Agenten ausführen; verwende dies nur auf Computern, Konten und Projekten, denen du vertraust.