local-mcp

English | 简体中文

A secure local developer runtime and Model Context Protocol (MCP) server for AI-assisted coding on macOS and other Unix-like development environments.

local-mcp gives AI clients structured access to local projects without exposing an unrestricted shell. It combines project trust, filesystem confinement, safe Git reads, controlled task execution, Developer Runtime state, workspace snapshots, and stdio/HTTP MCP transports.

Status

This project is currently in early development (0.1.0). The security model is intentionally conservative and may evolve before a stable release.

Related MCP server: Softority MCP Server

Features

• Project registration, discovery, trust and permission management

• Safe filesystem browsing, search, reading, writing and exact text replacement

• Protected path rules for .git, .env, private keys, .devmcp.yaml and other sensitive files

• Safe Git status, diff and log operations with external diff/textconv/fsmonitor protections

• Restricted task execution using structured program + args instead of shell command strings

• Project-root anchored executable allowlists

• Test, typecheck and lint execution

• Package script discovery and controlled execution

• Symbol definition/reference lookup

• Developer Runtime process management with dev_start, dev_logs, dev_stop and dev_list

• Workspace snapshots, restore previews and controlled restore

• Security scanning for risky project configuration and suspicious code patterns

• MCP over stdio and HTTP

• Loopback Host/Origin/Referer/Fetch-Metadata checks for local HTTP mode

• Request body, rate-limit, process-output and runtime resource limits

💡 Killer Feature: Seamless ChatGPT Web Integration (Unlimited Coding Without 5-Hour Caps)

When using ChatGPT Web for deep coding assistance, developers commonly face two bottlenecks:

1. Usage limits: Cloud-based Advanced Data Analysis (Code Interpreter) burns through strict 5-hour rate limits, causing popup lockouts that disrupt workflow.

2. Environment isolation: Cloud sandboxes cannot directly read, write, or run tests on your local machine, forcing frustrating manual copy-pasting.

How Does local-mcp Enable Unlimited Coding?

local-mcp connects ChatGPT Web to your local projects using a "Cloud Reasoning Brain + Local Execution Engine" architecture:

flowchart TD
    subgraph Cloud["☁️ Cloud Brain (OpenAI Cloud)"]
        User(["👤 Developer"]):::userNode -->|"Prompt / Coding Task"| WebUI["💻 ChatGPT Web<br/><b>Standard chat stream · Zero cloud sandbox quota consumed</b>"]:::cloudNode
        WebUI -->|"Intent parsing & Standard MCP tool calls"| Tunnel["🔒 Secure HTTPS Tunnel<br/><b>Cloudflare Tunnel / ngrok / Proxy</b>"]:::tunnelNode
    end

    subgraph Local["🖥️ Local Execution Engine (Your Machine)"]
        Tunnel -->|"Remote MCP (HTTP / SSE)"| Server["⚡ Local shmcp-http Server<br/><b>Bearer Token Auth + 16MB Streaming Fuse</b>"]:::serverNode

        Server -->|"Code Introspection"| TaskRead["🔍 Workspace search & AST symbol navigation"]:::localAction
        Server -->|"Precision Modification"| TaskWrite["📝 Safe filesystem write & exact patch"]:::localAction
        Server -->|"Local Build & Verification"| TaskTest["🧪 Run pnpm test / typecheck / lint"]:::localAction
        Server -->|"Process Lifecycle"| TaskDev["🚀 Supervise Dev Server & live logs"]:::localAction

        TaskRead --> Sandbox["🛡️ Multi-Layer Security Guard<br/><b>Path traversal defense · Credential shield · Read-only for untrusted</b>"]:::sandboxNode
        TaskWrite --> Sandbox
        TaskTest --> Sandbox
        TaskDev --> Sandbox

        Sandbox -->|"Real execution stdout & error stack traces"| Server
    end

    Server -->|"Stream JSON-RPC results"| WebUI
    WebUI -->|"Autonomous closed-loop self-correction"| User

    classDef cloudNode fill:#e8f4fd,stroke:#10a37f,stroke-width:2px,color:#111;
    classDef tunnelNode fill:#fff8e1,stroke:#ffa000,stroke-width:2px,color:#111;
    classDef serverNode fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px,color:#111;
    classDef localAction fill:#e8f5e9,stroke:#388e3c,stroke-width:1.5px,color:#111;
    classDef sandboxNode fill:#ffebee,stroke:#d32f2f,stroke-width:2px,stroke-dasharray: 4 4,color:#111;
    classDef userNode fill:#f5f5f5,stroke:#616161,stroke-width:2px,color:#111;

• Zero Cloud Sandbox Consumption: All file indexing, precise syntax patching, type checking, test runs, and dev server supervision occur directly on your local computer. It does not consume OpenAI's cloud container resources.

• Continuous All-Day Workflow: To ChatGPT Web, this operates through standard text/tool conversation streams, completely bypassing the strict 5-hour code execution limits so you can refactor, write features, and debug without interruption.

• Instant WYSIWYG Feedback: ChatGPT modifies code locally and runs test suites immediately, inspecting error stack traces and self-correcting autonomously without manual intervention.

Security model

The project is designed around four layers:

Global policy
    ↓
Project trust and project policy
    ↓
Developer Runtime
    ↓
Filesystem / Git / process / MCP tools

Project trust

Newly registered and auto-discovered projects are untrusted by default.

An untrusted project is treated as read-only:

• filesystem reads may be allowed by policy

• writes and deletes are disabled

• shell/task execution is disabled

• workspace restore is disabled

• repository-provided AGENTS.md content is not automatically injected into project context

Trust must be granted locally through the CLI:

shcli project trust <name>

Trust can be revoked with:

shcli project untrust <name>

Restricted execution is not a sandbox

Restricted mode limits executable resolution, arguments, environment variables and project-local executables. It does not provide operating-system sandboxing.

Package managers and build tools can execute project code. Task execution therefore still requires an explicitly trusted project.

Protected files

Default protected patterns include:

.git
.git/**
.vscode/**
.idea/**
.env
.env.*
*.pem
*.key
*.p12
*.pfx
id_rsa
id_ed25519
.devmcp.yaml

Protected files cannot be read or modified through normal filesystem MCP tools.

Requirements

• Node.js >= 22.12.0

• pnpm

• macOS or another Unix-like development environment is the primary target

Optional tools such as Git, ripgrep, Go, Swift, Flutter or Gradle are required only for the related project features.

Development

Install dependencies:

pnpm install --frozen-lockfile

Run the checks:

pnpm test
pnpm typecheck
pnpm build

Clean generated output:

pnpm clean

CLI & MCP Server

The management CLI is:

shcli

Useful management commands include:

shcli project add <path>
shcli project list
shcli project trust <name>
shcli project untrust <name>
shcli doctor
shcli config

The standalone stdio MCP server executable remains:

shmcp

MCP stdio server

Connect AI clients (Claude Desktop, Cursor, etc.) directly using:

shmcp

For local development:

pnpm dev:mcp

Installation via Smithery (One-Click)

To install for Claude Desktop or Cursor automatically via Smithery:

npx -y @smithery/cli install @shworks/local-mcp --client claude

MCP HTTP server

The HTTP executable is:

shmcp-http

Default configuration:

Host: 127.0.0.1
Port: 8787

Supported environment variables:

MCP_HOST
MCP_PORT
MCP_AUTH_TOKEN
MCP_ALLOW_INSECURE_HTTP
MCP_MAX_BODY_BYTES
MCP_ALLOWED_HOSTS

MCP_ALLOWED_HOSTS is only for trusted HTTP Host values (for example, a reverse-proxy hostname). Authenticated MCP requests do not depend on browser Origin / Referer headers. Browser-source checks are enforced only for unauthenticated loopback mode.

Example:

MCP_AUTH_TOKEN="replace-with-a-strong-token" \
MCP_HOST="127.0.0.1" \
MCP_PORT="8787" \
shmcp-http

Non-loopback HTTP requires authentication. Plain HTTP on a non-loopback address is rejected by default and must be explicitly enabled with:

MCP_ALLOW_INSECURE_HTTP=1

For remote access, prefer an HTTPS reverse proxy instead of exposing plaintext HTTP.

Connecting with ChatGPT Web (3 Steps to Unlimited Coding)

Connecting your local workspace to ChatGPT Web takes only three simple steps:

Step 1: Start shmcp-http with a Secure Auth Token

MCP_AUTH_TOKEN="set-your-strong-random-token" \
MCP_HOST="127.0.0.1" \
MCP_PORT="8787" \
shmcp-http

Step 2: Expose via Secure HTTPS Tunnel (Cloudflare Tunnel or ngrok)

Since ChatGPT Web runs in the cloud, expose your local port via a secure tunnel:

# Using Cloudflare Tunnel (cloudflared):
cloudflared tunnel --url http://127.0.0.1:8787

# Or using ngrok:
ngrok http 8787

You will receive a public HTTPS URL such as https://your-tunnel.trycloudflare.com.

Step 3: Create a Dedicated Assistant via GPTs Editor (Official Method for Plus / Team)

💡 Important Note: In ChatGPT Plus Web, global MCP tools cannot be attached directly in generic chat windows. The official, stable way supported by OpenAI is creating a dedicated assistant via My GPTs:

1. Open the official GPT Editor in your browser: https://chatgpt.com/gpts/editor.

2. Switch to the Configure tab:

   • Name: Enter Local Dev Assistant (or your preferred name).

   • Instructions: Add a concise prompt, e.g.:

     "You are an expert full-stack local coding assistant. Always use the connected local MCP tools to inspect code, edit files, and execute tests before answering."

3. Scroll down to the bottom, find Actions, and click Create new action:

   • Authentication: Select API Key, Auth Type Bearer, and enter the MCP_AUTH_TOKEN from Step 1.

   • Schema: Click Import from URL and enter https://your-tunnel.trycloudflare.com/openapi.json (ChatGPT will automatically import the OpenAPI 3.1.0 schema).

4. In the top-right corner, click Create / Update and choose Only me to save.

5. Start Unlimited Pairing:

   • In the ChatGPT Web sidebar, click on your newly created custom GPT at any time.

   • Pair-program naturally in the browser chat:

     "Inspect our project README, find uncovered edge cases in packages/core, apply fixes, and run pnpm test to verify!"

All reasoning flows through standard chat, while code execution and test verification run on your local machine without burning through strict 5-hour Code Interpreter quotas!

Project configuration

Projects may define .devmcp.yaml for controlled tasks and project-specific restrictions.

Example:

permissions:
  read: true
  write: true
  delete: false
  shell: restricted

commands:
  test:
    program: pnpm
    args: ["test"]
    cwd: "."
    timeoutMs: 120000

  typecheck:
    program: pnpm
    args: ["typecheck"]
    cwd: "."
    timeoutMs: 120000

  build:
    program: pnpm
    args: ["build"]
    cwd: "."
    timeoutMs: 180000

A project configuration can restrict the global policy further, but cannot elevate permissions beyond the global policy.

.devmcp.yaml itself is protected and symbolic links are rejected.

Developer Runtime

Stateful tools use a Developer Runtime to keep bounded local state such as:

• recent test results

• managed development processes

• workspace snapshots

Runtime resources are bounded and can be reset without changing project files outside the controlled restore mechanism.

Representative tools include:

test_run
test_failures
typecheck
lint
symbol_definition
symbol_references
dev_start
dev_list
dev_logs
dev_stop
package_scripts
package_run_script
workspace_snapshot
workspace_snapshot_list
workspace_restore_preview
workspace_restore
security_scan
runtime_status
runtime_capabilities
runtime_reset

Installation & Release Gate

Currently, build the project from source or link globally using pnpm.

Before creating a release, the intended release gate is:

pnpm install --frozen-lockfile
pnpm test
pnpm typecheck
pnpm build

A release should use an immutable Git tag and source archive with a verified SHA-256 checksum.

Reporting security issues

Please avoid publishing exploitable security issues in a public issue before a fix is available. If a private security reporting channel is configured for the repository, use that channel first.

Discovery & Machine Introspection

The HTTP server provides standard machine-readable discovery endpoints so AI clients, reverse proxies, and developer portals can discover server capabilities automatically:

GitHub Topics for Discovery

When hosting on GitHub, add these repository topics to ensure automated crawlers (Smithery, PulseMCP, Glama) index your server: mcp, mcp-server, model-context-protocol, chatgpt-actions, claude-desktop, cursor, developer-tools

License

Licensed under the Apache License, Version 2.0. See LICENSE.