# Local Workspace MCP

> Local Workspace MCP is a free MCP server for developer tools. Read-only filesystem, git and allowlisted-task access to local project folders. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** CLI, macOS, Linux, Windows
- **Repository:** https://github.com/peter4leadson/local-workspace-mcp
- **MCP Registry name:** io.github.peter4leadson/local-workspace-mcp
- **Categories:** developer tools, files and documents
- **Listing updated:** 2026-11-17

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/local-workspace-mcp
