Local Agent MCP

English · Permisos · Arquitectura

Haz que ChatGPT Pro trabaje directamente en tu ordenador local

Le das una tarea a ChatGPT y puede invocar las herramientas MCP locales: leer proyectos, modificar archivos, ejecutar pruebas, revisar el Git Diff y crear Commits.

Las tareas complejas se pueden delegar al Codex local. ChatGPT sigue encargándose de dividir los pasos, revisar el progreso, añadir requisitos y hacer la comprobación final.

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

No hace falta copiar y pegar código repetidamente, ni desviar cada tarea a Codex.

Este es un proyecto comunitario no oficial. No es un producto de OpenAI ni representa a OpenAI.

Related MCP server: chatgpt-codex-tools-mcp

Inicio rápido

Requisitos previos

Prepara lo siguiente:

• macOS o Linux

• Python 3.11 o superior

• Git

• uv

• El tunnel-client oficial de OpenAI

• Un entorno de ChatGPT compatible con MCP Apps personalizadas

• Un Tunnel ID

• Una Tunnel Runtime Key correspondiente

En macOS puedes instalar primero las herramientas básicas:

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

Entrégaselo a la IA en una frase

Envía esta frase a una IA que pueda operar un terminal local:

Instala https://github.com/ezra-y/local-agent-mcp en mi ordenador y completa la configuración, el arranque y la verificación según el README.

Instalación manual: Instalación en ChatGPT.

Características destacadas

28 herramientas

No se expone una Tool delete_file directa. apply_patch también rechaza eliminar archivos completos.

git_commit desactiva por defecto los Hooks del repositorio y las firmas de confirmación. Si detecta Git Filters clean / process, rechaza la confirmación para evitar que un Commit estructurado ejecute programas del repositorio de forma implícita. git_diff también desactiva los Diff externos y textconv.

Recurso de permisos

Además de la Tool get_permissions, el servicio ofrece:

local-agent://permissions

El contenido incluye:

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

get_permissions se mantendrá para los clientes que aún no muestran MCP Resources.

Permisos y reducción de privilegios

Alcance por defecto

Las herramientas de archivos estructurados y Git pueden acceder por defecto al Home del usuario actual:

$HOME

Normalmente incluye Desktop, Downloads, Documents y otros proyectos en directorios personales.

Contenido prohibido por código

Las herramientas de archivos estructurados rechazarán:

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

Además:

• No hay una Tool de eliminación directa de archivos.

• apply_patch no puede eliminar archivos completos.

• No hay Tool de Git Push.

• git_commit solo confirma las rutas listadas explícitamente.

Reducir el alcance estructurado

Configura antes de iniciar:

export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"

El nombre de configuración antiguo CODEX_MCP_ROOT sigue siendo compatible.

Después, estas herramientas solo pueden acceder a $HOME/Projects:

list_files
read_file
write_file
apply_patch
git_status
git_diff
git_commit

Ejemplo de inicio en primer plano:

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

Puntos de entrada con privilegios elevados

LOCAL_AGENT_MCP_ROOT es el límite estricto para las herramientas de archivos estructurados y Git, no un sandbox de sistema para todo el proceso.

Si necesitas Hooks de repositorio, Git LFS u otros Filters, haz el Commit manualmente o usa run_command con privilegios elevados tras comprobar explícitamente la configuración del repositorio.

v0.5.1 no tiene por ahora una configuración para ocultar o desactivar Tools individualmente. Si necesitas un aislamiento más fuerte, puedes usar un usuario de sistema independiente, una máquina virtual, un contenedor o mantener una versión con Tools recortadas.

La documentación completa está en docs/permissions.md.

Instalación en ChatGPT

1. Descargar y probar

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

El orden de búsqueda del Codex local:

1. La ruta especificada por CODEX_BIN.

2. codex en PATH.

3. El Codex integrado en la App de ChatGPT para macOS.

2. Guardar la Runtime Key

macOS:

./scripts/save_tunnel_key.sh

Linux:

export CONTROL_PLANE_API_KEY="<你的 Runtime Key>"

3. Generar la configuración del Tunnel

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

La configuración local se guarda en:

.runtime/profiles/

4. Iniciar el Tunnel

En primer plano:

./scripts/run_tunnel.sh

En segundo plano:

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

Espera a que el servicio esté listo:

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

En caso de éxito devuelve:

ready

Página de estado local:

http://127.0.0.1:8741/ui

5. Conectar en ChatGPT

1. Abre Settings → Apps.

2. Activa Developer Mode.

3. Crea o conecta la MCP App personalizada correspondiente.

4. Tras iniciar el Tunnel, haz clic en Refresh / Scan tools.

5. Abre un chat nuevo y selecciona @Local Agent.

6. Verificar

Envía en un chat nuevo:

@Local Agent

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

Resultado esperado en v0.5.1:

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

Si el cliente admite Resources, intenta también leer:

local-agent://permissions

Ejecutar solo el MCP stdio local

Sin usar el Tunnel de ChatGPT:

./scripts/run_mcp.sh

También se puede instalar como comando global:

uv tool install .
local-agent-mcp

El comando antiguo local-codex-mcp sigue disponible.

Uso diario

El parámetro project de las herramientas suele rellenarse con una ruta relativa a $HOME:

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

También se admiten rutas absolutas dentro del Home. project="." representa todo el directorio raíz estructurado; con la configuración por defecto, todo el Home.

Una tarea habitual

@Local Agent

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

Flujo habitual:

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

Para tareas complejas se puede añadir un Workflow explícito o el Codex local.

Cómo funciona el Workflow

Cinco conceptos

Orden de ejecución

create_workflow
→ create_step
→ start_step
→ get_job / get_workflow

create_step admite actualmente cuatro tipos de ejecución:

La lectura y modificación de archivos se sigue haciendo directamente con read_file, write_file y apply_patch.

Ejemplo: crear un Step de prueba

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)

La identidad de ejecución es:

workflow_id + step_id + attempt

Si se inicia de nuevo con el mismo número, devuelve el Job original y no se ejecuta de nuevo. Para una repetición explícita, usa un attempt nuevo, por ejemplo attempt=2.

Reglas de paralelismo

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

Cuando un Turn activo necesite requisitos adicionales, usa steer_codex_turn; para detenerlo, usa interrupt_codex_turn.

Estado local y registros

Al ejecutar desde el código fuente:

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

El comando instalado usa por defecto:

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

Ubicación personalizada:

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

El nombre de configuración antiguo CODEX_WORKFLOW_STATE_PATH sigue siendo compatible. Los estados antiguos existentes también se siguen leyendo.

Los registros largos se guardan en archivos Artifact. SQLite guarda la ruta, el tamaño y el SHA-256.

Los Artifacts no se eliminan automáticamente. Cuando el total registrado supera 1 GiB, ping devuelve una advertencia.

Actualización

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

Después, reinicia el Tunnel y haz clic en Refresh / Scan tools en ChatGPT.

Estructura del proyecto

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 启动脚本

Los archivos de prueba se conservan en el repositorio. Se usan para verificar los límites de permisos, la ejecución multiplataforma, el empaquetado y la compatibilidad; el wheel instalado solo contiene el código de ejecución.

Comprobaciones de desarrollo

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

La entrada principal del MCP es src/local_agent_mcp/server.py. src/codex_bridge.py se mantiene como alias de compatibilidad para importaciones y formas de inicio antiguas.

Desinstalación y datos locales

El programa de desinstalación no elimina automáticamente SQLite, Artifacts, el perfil del Tunnel ni el directorio del código fuente. Revisa primero y decide qué datos quieres conservar.

Licencia

MIT, ver LICENSE.

⚠️ La configuración por defecto abre permisos locales amplios: ChatGPT puede leer y escribir en la mayoría de los proyectos del Home del usuario actual, y puede ejecutar pruebas, comandos y Agents locales; úsalo solo en ordenadores, cuentas y proyectos de confianza.