Local Workspace MCP server

local-workspace-mcp

Your AI assistant needs context. It does not need unrestricted access.

A read-oriented MCP server for local workspaces. Write, delete, and arbitrary-shell tools do not exist in it. Not gated or disabled: absent. Every filesystem path is checked against operator-authorized roots and a default-deny list for secrets, .env files, private keys, and .git internals. Git read tools and operator-declared named tasks provide bounded capability without giving the model a shell.

read-only git (status/diff/log/show/branches), multimodal file inspection (images/archives/PDF/Office), and task_run for explicitly allowlisted commands.

• 23 tools over stdio JSON-RPC: bounded filesystem reads/searches,

No inbound listener, no daemon; the server itself makes no network calls (allowlisted tasks run as your user and are not network-restricted).

• One transport: each MCP host spawns workspace-mcp serve --stdio.

allowlist bounds what can be invoked, not what invoked code can do. It is not a sandbox.

• Honest scope: task_run executes real commands as your user. The

Evaluating this for team use? Start at docs/THREAT-MODEL.md and SECURITY.md.

Contents: The problem · Quick start · Usage · Tool surface · Supported hosts · Permission model · What it will not do · Security architecture · Configuration · Troubleshooting · Compatibility · Verifying the build · Release status

The problem

Hosts' built-in file tools are convenient but live in the client's permission loop, the same loop users bypass out of fatigue (--dangerously-skip-permissions, "yes to everything"). The official @modelcontextprotocol/server-filesystem ships read and write tools with no default secrets denylist, and has already overwritten a user's .env (upstream issue #1869). Generic filesystem MCPs give a model file access; they do not give it bounded access.

This server moves the boundary server-side: roots, deny rules, task allowlists, and audit live in an operator config that repository content cannot widen. A compromised or bypassed prompt loop cannot invoke a tool that does not exist.

Quick start

Requires Node ≥ 20, plus git for git_* tools and ripgrep (rg) for content search. Building from a clone needs pnpm (corepack enable).

npm install -g local-workspace-mcp          # puts workspace-mcp on PATH

# or from a clone:
pnpm install && pnpm build && npm link

workspace-mcp init-config     # writes ~/.config/local-workspace-mcp/config.json (mode 600)

# REQUIRED: replace the example workspace path with a real absolute path —
# any editor works; doctor fails until you do
nano ~/.config/local-workspace-mcp/config.json

workspace-mcp doctor          # must print "doctor: ALL GREEN" (use --json for CI)

The generated config ships a placeholder workspace named example — replace it with a real root or doctor will report root.example FAIL. A healthy run ends:

PASS policy.selftest — 9/9 cases correct
PASS mcp.startup — tool registration ok
doctor: ALL GREEN

Minimal working config (strict JSON — no comments or trailing commas):

{
  "version": 1,
  "workspaces": {
    "myproj": { "path": "/absolute/path/to/repo", "tasks": [] }
  },
  "tasks": {},
  "deny": []
}

Then register the server with a host. For Claude Code:

Shortened. The full README is on GitHub.