Saltar a contenido

Inicio rápido

Esta guía usa Docker Compose como primer runtime y ChatGPT como primer client. Son decisiones independientes: Docker, VS Code extension, binary, Python y stdio son opciones de runtime; ChatGPT y los clientes MCP genéricos son opciones de client. Consulte opciones de runtime y modelo de despliegue para ver el mapa completo.

Requisitos

  • Docker Engine con Compose v2.
  • Un endpoint HTTPS público si ChatGPT debe conectarse desde la web.
  • Un directorio de workspace dedicado.
  • Un OAuth admin PIN y JWT secret largos y aleatorios.

Warning

El modelo conectado puede operar el workspace configurado. Ejecute el servicio en un container o VM desechable y evite montar recursos de control del host.

1. Clonar y configurar

git clone https://github.com/fwerkor/local-shell-mcp.git
cd local-shell-mcp
cp .env.example .env

Edite .env:

LOCAL_SHELL_MCP_PUBLIC_BASE_URL=https://your-public-host.example.com
LOCAL_SHELL_MCP_AUTH_MODE=oauth
LOCAL_SHELL_MCP_OAUTH_ADMIN_PIN=change-me-long-random-pin
LOCAL_SHELL_MCP_OAUTH_JWT_SECRET=change-me-64-hex-random-secret
CLOUDFLARE_TUNNEL_TOKEN=

2. Iniciar el servidor

mkdir -p workspaces/default
docker compose up -d

Compruebe el estado:

docker compose ps
docker compose logs --tail=100 local-shell-mcp
curl -i http://127.0.0.1:8765/healthz

Una respuesta sana devuelve HTTP 200.

3. Exponer HTTPS

Para el sidecar de Cloudflare Tunnel:

docker compose --profile tunnel up -d

En Cloudflare Zero Trust, apunte el public hostname a:

http://local-shell-mcp:8765

Con Caddy, Nginx, Traefik, Nginx Proxy Manager u otro reverse proxy, reenvíe el tráfico HTTPS a 127.0.0.1:8765 o a la dirección de red del container.

4. Conectar ChatGPT

Use el endpoint MCP:

https://your-public-host.example.com/mcp

Siga la guía del conector de ChatGPT para completar OAuth y la aprobación de herramientas.

5. Confirmar de forma segura el acceso a herramientas

Pida al modelo:

Usa local-shell-mcp. Primero llama a environment_get y después enumera la raíz del workspace. No modifiques archivos todavía.

Herramientas de solo lectura esperadas:

  • environment_get
  • file_list
  • file_tree
  • file_read

6. Empezar con una tarea de programación acotada

Una buena primera tarea:

Inspecciona este repository, resume la estructura del proyecto, ejecuta la suite de tests existente si es evidente y no cambies archivos.

Una vez confirmada la conectividad, dé instrucciones más específicas:

Corrige el test que falla. Lee primero los archivos relevantes, haz el patch más pequeño, ejecuta el test objetivo y después muestra git diff. No hagas commit hasta que lo apruebe.

Actualización

docker compose pull
docker compose up -d
curl -i http://127.0.0.1:8765/healthz

Si usa el perfil tunnel:

docker compose --profile tunnel pull
docker compose --profile tunnel up -d
curl -i http://127.0.0.1:8765/healthz

Páginas siguientes

Necesidad Página
Entender las opciones de runtime y client Opciones de runtime y modelo de despliegue
Ejecutar con Docker Compose Docker Compose runtime
Ejecutar desde VS Code VS Code extension runtime
Ejecutar con un binary de release Runtime binary independiente
Ejecutar con Python o source checkout Python runtimes
Añadir ChatGPT como client ChatGPT connector
Elegir herramientas y escribir mejores prompts Patrones de uso
Conectar una máquina HPC, NPU/GPU o NAT Workers remotos
Entender todas las herramientas MCP Referencia de herramientas