Local Coder MCP

Self-hosted MCP coding tools for your local workspaces, available to any compatible AI client.

Works with: ChatGPT, Gemini, Claude, Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, Le Chat, and other MCP clients.

Any MCP client ─── HTTPS tunnel (optional) ───► MCP :8787
Browser on this machine ──────────────────────► Admin :8788 (loopback only)
                                                   │
                                      Docker ──────┴── /data + mounted projects

Quick start

1. Clone the repository:

   git clone https://github.com/Yassinecoder06/Local_Coder_MCP.git && cd Local_Coder_MCP

2. Run ./scripts/setup.sh (or ./scripts/setup.sh --yes to accept defaults). Docker Compose v2 is required.

3. Open http://localhost:8788 and copy the connection URL and access key shown on the admin Connect page.

4. Connect any compatible client using the endpoint and access key on the admin Connect page. Remote clients need a public HTTPS URL; see Getting a public HTTPS URL.

Your project directory defaults to ~/Projects. It is mounted at the same absolute path inside the container, so file paths stay identical. Change it in .env and restart with docker compose up -d.

Related MCP server: DevSpace

Connect your client

Use the MCP URL shown on the admin Connect page, normally <base>/mcp, and the access key shown there. Choose OAuth and sign in with the access key, or configure the client to send Authorization: Bearer <key>. Some clients support the URL form <base>/mcp/<key> instead. Remote clients must be able to reach the server over HTTPS; see Getting a public HTTPS URL. Client menus, plan availability, and configuration formats can change; use the linked client documentation for current details.

Getting a public HTTPS URL

Web clients cannot reach localhost. Start an ephemeral Cloudflare Quick Tunnel:

docker compose --profile tunnel up -d

The server discovers the Quick Tunnel URL automatically from Cloudflare's tunnel metrics endpoint. It appears in the admin UI once the tunnel is up; no manual PUBLIC_URL setting is needed. Quick Tunnel URLs change when the tunnel is recreated. For a stable hostname, create a Cloudflare named tunnel, put its token in CLOUDFLARE_TUNNEL_TOKEN, then start it with docker compose --profile named-tunnel up -d named-tunnel and set PUBLIC_URL to its configured hostname. Tailscale Funnel and ngrok are alternatives; point either at the MCP port 8787 and set PUBLIC_URL to its HTTPS URL.

Already have your own domain or Cloudflare tunnel?

Point your existing tunnel or reverse proxy at the host port set by PORT in .env. For example, PORT=3000 publishes host port 3000 and passes HOST_PORT=3000 to the server. Set PUBLIC_URL=https://your-domain. You do not need the tunnel profile. The server always listens on port 8787 inside the container; PORT only selects the host port that Compose publishes. For a tunnel running in a separate container on this Compose network, target http://mcp:8787 instead.

The admin port remains bound to 127.0.0.1 and is never sent through the tunnel.

Fewer permission prompts

Choose an approval mode in .env or switch it live in Admin → Settings:

• Trust never asks for confirmation. It marks every tool as read-only to the client. Use this only if you trust the prompts and content in your workspace: text the AI reads could instruct it to run commands without asking.

• Minimal is the default. Read-only tools never ask. Only four tools ask once each: edit_files, run, git_write, and skill_save. In clients with per-tool approval controls, click Always allow once per tool.

• Standard uses conservative annotations, so clients may ask for confirmation each time a mutating or command tool runs.

Skills

Add skills in data/skills/, import them in the admin UI, or ask the chat to use skill_save. A skill is a folder containing SKILL.md:

---
name: release-check
description: Check a project before release.
---

Inspect the working tree, run the project's checks, and summarize any release blockers.

Built-in skills: herdr, ui-design, code-review, git-workflow, skill-authoring, and docker-dev. Setup mounts host skills when it detects a usable Herdr integration (see Docker setup).

Commands

Built-ins: /review, /test, /fix, /commit, /explain, /plan, /scaffold, /docs, /refactor, /deps, /onboard, /ship, /verify, /todo, and /resume. Add user commands in data/commands/ or through the admin UI; each command is a Markdown file with a name, description, optional arguments, and prompt template.

Herdr integration

When setup finds the Herdr CLI and its live socket, it enables the host-tools Compose override automatically and prints herdr integration: enabled. The override mounts the CLI and Herdr config directory, sets the Herdr environment, and makes the herdr skill available. Otherwise it prints herdr integration: disabled; install/start Herdr and run setup again to enable it. Set HERDR_BIN in .env if the CLI is installed outside the detected path.

This lets a connected AI client use the herdr skill to inspect and drive real host terminals and CLI agents. Herdr can send commands and input to those terminals, so protect the Local Coder access key and only connect clients you trust.

Verification

After edits, inspect diagnostics and run the project's checks so the model can report evidence that the change works. Use /verify to identify and run relevant checks; for UI changes, open the running page with browser_check and inspect its screenshot. Use /todo to keep a concrete checklist for multi-step work and /resume to continue from unfinished items later.

Tools

The default TOOL_PROFILE=essential is tuned for web chat. Set TOOL_PROFILE=full in .env to expose additional tools as they are available.

Configuration

Values are set in .env. Compose binds both ports to loopback and mounts /data for persistent state.

HOST, ADMIN_HOST, and WORKSPACE_ROOTS are also supported by the app. Docker sets the listener hosts to 0.0.0.0 internally and derives workspace roots from PROJECTS_DIR.

Run without Docker

With Node.js 22 or later:

npm ci
npm run build
npm start

Set WORKSPACE_ROOTS, MCP_TOKEN, and DATA_DIR in your environment as needed. The admin listener defaults to loopback; keep it local or protect it with your own network controls.

Security

The server can read and change files and run shell commands in mounted workspaces. Connect only to a server you control, use a strong access key, review tool actions, and keep the admin port local. For internet access, expose only the MCP port through a trusted HTTPS tunnel. Avoid AUTH_MODE=none except for isolated local testing.

Troubleshooting

• Docker says PROJECTS_DIR is missing: run ./scripts/setup.sh or set an absolute PROJECTS_DIR in .env.

• Admin page does not load: check docker compose ps and docker compose logs mcp; use http://localhost:8788 on the Docker host.

• Client cannot connect: web clients need an HTTPS tunnel; Quick Tunnel URLs appear automatically, while named tunnels and other providers need the matching PUBLIC_URL.

• Files are owned by the wrong user: confirm HOST_UID and HOST_GID in .env match id -u and id -g, then recreate the service.

• Quick Tunnel URL is missing: wait a few seconds and check docker compose --profile tunnel logs -f tunnel.

License

MIT. See LICENSE.