Local Workspace MCP

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.

• 23 tools over stdio JSON-RPC: bounded filesystem reads/searches, read-only git (status/diff/log/show/branches), multimodal file inspection (images/archives/PDF/Office), and task_run for explicitly allowlisted commands.
• One transport: each MCP host spawns workspace-mcp serve --stdio. The server itself has no inbound listener, keeps no daemon, and makes no network calls (allowlisted tasks run as your user and are not network-restricted; the ChatGPT tunnel path below runs a supervised tunnel-client process instead of a host-spawned one).
• Honest scope: task_run executes real commands as your user. The allowlist bounds _what can be invoked_, not what invoked code can do. It is not a sandbox.

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:

claude mcp add local-workspace --scope user -- workspace-mcp serve --stdio

claude mcp list # confirm it registered

Other hosts use config-file entries (below — substitute the absolute path from which workspace-mcp). Then ask: _"use workspace_roots, then fs_list on myproj"_. First useful call sequence: fs_list → git_status → git_diff on uncommitted work, where a chat client otherwise has no eyes.

Usage examples

# what the assistant can ask for

workspace_roots # authorized workspace ids, no host paths fs_list {workspace:"myproj"} fs_read {workspace:"myproj", path:"src/index.ts", startLine:1, maxLines:120} fs_search_content {workspace:"myproj", query:"TODO"} # literal; regex:true for rg syntax git_status {workspace:"myproj"} # branch, HEAD, uncommitted truth git_diff {workspace:"myproj"} # worktree diff, bounded output git_show {workspace:"myproj", spec:"HEAD"} task_list {workspace:"myproj"} task_run {workspace:"myproj", taskId:"typecheck"}

Denied behavior is explicit, never silent:

fs_read {workspace:"myproj", path:".env"}              → ACCESS_DENIED  (or NOT_FOUND if absent)

fs_read {workspace:"myproj", path:"../../outside-root.txt"} → OUTSIDE_ROOT task_run {workspace:"myproj", taskId:"nuke"} → TASK_DENIED (valid id, not enabled) task_run {workspace:"myproj", taskId:"rm -rf /"} → INVALID_ARGUMENT (malformed task id) git_show {workspace:"myproj", spec:"--exec"} → INVALID_ARGUMENT

Denial codes are the policy working as intended, not errors to report; widening access happens only in the operator config. Task/search timeouts and output limits return timedOut:true/truncated:true in a normal result rather than an error. INTERNAL_ERROR covers spawn/tool failures and should not appear in healthy use; git_* on a non-git root returns {repo:false} gracefully.

Tool surface

All 23 tools, annotated readOnlyHint where true (hosts can auto-approve pure reads). task_run is the only tool with side effects.

Supported hosts

GUI hosts (Claude Desktop especially) spawn servers with a minimal PATH, not your shell's.