Skip to content
MCP server

Local Workspace MCP

Read-only filesystem, git and allowlisted-task access to local project folders

Runs locallyStatus and history
Install
Pricing
Free
Platforms
CLI, macOS, Linux
Runs
Locally
Version
0.2.2
Listing updated
today

About Local Workspace MCP

Local Workspace MCP is a free MCP server for developer tools. It runs locally on your machine and is started by your AI client.

Local Workspace MCP is built on the idea that an assistant needs context but not unrestricted access. Write, delete and arbitrary-shell tools do not exist in it, rather than being disabled. Each path is checked against operator-authorised roots and a default deny list covering secrets, .env files, private keys and .git internals, with explicit denial codes such as ACCESS_DENIED and OUTSIDE_ROOT.

Its 23 tools cover bounded file reads and searches, read-only git (status, diff, log, show, branches), inspection of images, zip archives, PDFs and Office files, and task_run, the one tool with side effects, which only runs commands you declared in config. The README is candid that this is not a sandbox: allowlisted tasks run as your user and can do whatever the command does.

It runs over stdio only, has no network listener or daemon, and needs Node 20 or newer, with git and ripgrep for some tools. A doctor command validates the config, and the repository includes a threat model and security policy for teams evaluating it.

Install

Run in a terminal

claude mcp add local-workspace-mcp -- npx -y local-workspace-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "local-workspace-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "local-workspace-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "local-workspace-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "local-workspace-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "local-workspace-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "local-workspace-mcp"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "local-workspace-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "local-workspace-mcp"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "local-workspace-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "local-workspace-mcp"
      ]
    }
  }
}

Tools this server provides (18)

Taken from the project documentation; the running server may differ.

workspace_roots
Lists authorized workspace ids without host paths
fs_list
Lists files in a workspace
fs_read
Reads a file with line bounds
fs_search_content
Searches file contents literally or with ripgrep regex
git_status
Shows branch, HEAD and uncommitted state
git_diff
Shows a bounded worktree diff
git_show
Shows a commit or object
task_list
Lists declared tasks for a workspace
task_run
Runs an allowlisted named task
fs_inspect
Detects file kind and returns size, hash and hints
fs_image
Returns an image as a native image block
fs_contact_sheet
Builds a labeled montage of up to 24 images
fs_archive_list
Lists members of a zip
fs_archive_entry
Reads one archive member
fs_pdf_info
Returns PDF page count and text-layer presence
fs_pdf_page
Renders up to 4 PDF pages as images
fs_pdf_text
Extracts text from up to 50 PDF pages
fs_office_text
Extracts text from docx, pptx and xlsx files

What it does

No write tools
Write, delete and shell tools are absent, not just switched off.
Authorised roots
Every path must sit inside operator-configured workspace roots.
Secret deny list
Blocks .env files, private keys and .git internals by default.
Read-only git
Status, diff, log, show and branches without a shell.
Rich file inspection
Reads images, archives, PDFs and Office documents.
Named tasks
Runs only commands the operator has explicitly allowlisted.

Good for

  • Let an assistant review uncommitted changes without write access
  • Search a codebase while keeping secrets out of reach
  • Have a model read PDFs or Office files inside a project folder
  • Run a single approved typecheck or test task

Pricing

Free

Free npm package

Local Workspace MCP FAQ

Can it modify my files?

No. It has no write, delete or arbitrary-shell tools.

Is task_run sandboxed?

No. The README says allowlisted tasks run as your user and the list only bounds what can be invoked.

What does it need?

Node 20 or newer, plus git and ripgrep for the related tools.

Does it make network calls?

The server itself makes none, though allowlisted tasks are not network-restricted.

Is Local Workspace MCP free?

Yes. Local Workspace MCP is free to use.

How do I add Local Workspace MCP to Claude Code?

Run this command in your terminal: claude mcp add local-workspace-mcp -- npx -y local-workspace-mcp

What are the best alternatives to Local Workspace MCP?

The closest alternatives to Local Workspace MCP are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to Local Workspace MCP

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools