Local Workspace MCP

What local-workspace-mcp does

The local-workspace-mcp MCP server gives an AI host read-oriented access to configured local workspaces. It covers directory listings, file metadata, bounded text reads, batch reads, filename searches, content searches, and workspace discovery. Git operations provide status, diffs, logs, commit or object inspection, and branch information without exposing write operations.

The server also handles selected file formats. Agents can inspect images, create contact sheets, list archive members, read safe archive entries, inspect and render PDFs, extract PDF text, and extract text from Office Open XML files. Macros are flagged rather than executed, and legacy OLE content is refused. These capabilities place the project in the 📂 File Systems category while extending beyond plain text files.

How it works

Each MCP host starts workspace-mcp serve --stdio. The process keeps no daemon and opens no inbound network listener. Authorized roots are represented by workspace IDs; tool calls use those IDs and relative paths rather than exposing host paths through the workspace-discovery response.

The local-workspace-mcp MCP server checks every filesystem path against the configured root and default-deny rules. The deny policy covers secrets, .env files, private keys, and .git internals. Attempts to escape a root, read denied content, use an invalid Git specification, or invoke an unavailable task return explicit policy results such as OUTSIDE_ROOT, ACCESS_DENIED, or TASK_DENIED.

task_run is the only side-effecting tool. It runs an operator-declared task as the current user, so its allowlist limits which commands can be invoked but does not sandbox the code those commands execute. Search and task limits report timeout or truncation in normal results. Git calls on a non-Git root return a non-repository result rather than treating that condition as a failure.

Setup and configuration

Node.js 20 or newer is required. Git is needed for the git_* tools, and ripgrep is needed for content search. Installation can use the published npm package, or a clone can be built with pnpm before linking the command.

Run workspace-mcp init-config to create the configuration file, then replace the generated example path with an absolute workspace path. The configuration is strict JSON and defines a version, named workspaces, tasks, and deny settings. Run workspace-mcp doctor; setup is complete when it reports doctor: ALL GREEN.

Register the stdio command with the MCP host. For Claude Code, the documented command is claude mcp add local-workspace --scope user -- workspace-mcp serve --stdio. Other hosts use their MCP configuration-file format and the absolute path to workspace-mcp when required.

Tools and capabilities

The local-workspace-mcp MCP server exposes 23 tools, including:

• workspace_roots, fs_list, fs_stat, fs_read, fs_read_many, fs_search_files, and fs_search_content for bounded workspace navigation and search.
• fs_inspect, fs_image, fs_contact_sheet, archive tools, PDF tools, and fs_office_text for structured or multimodal inspection.
• Git read tools for status, diffs, logs, object display, and branches.
• task_list and task_run for operator-defined named tasks.

Reads are annotated with readOnlyHint where applicable, allowing compatible hosts to distinguish them from the task tool.

Limitations and notes

There are no write or delete tools, and the server does not provide an arbitrary shell tool. However, allowlisted tasks are real commands running with the user's permissions; the project explicitly does not treat this mechanism as a sandbox. Hosts and operators should review the threat model and security documentation before team deployment. Access can be widened only through operator configuration, not through repository content or prompts.