# Claude Work MCP

Local MCP server for connecting Claude Code to your work environment through explicit, auditable tools.

## What it exposes

- `list_work_tools`: shows the active config, workspace root, links, endpoints, and safety gates.
- `list_work_files`: lists files under `workspaceRoot`.
- `read_work_file`: reads UTF-8 text files under `workspaceRoot`.
- `search_work_files`: searches text files under `workspaceRoot`.
- `write_work_file`: writes files only when `allowWrite=true`.
- `read_handoff` / `append_handoff`: shared Codex-Claude notes.
- `call_work_api`: calls only HTTP endpoints defined in `config/work-tools.local.json`.
- `run_work_command`: runs only allowlisted commands and only when `allowCommands=true`.

## Install dependencies

```powershell
cd "C:\Users\Peruano Pinto\Documents\Codex\2026-07-09\necesito\work\claude-work-mcp"
npm install
npm run build
npm run smoke
```

## Register with Claude Code on Windows

After installing Claude Code, run:

```powershell
cd "C:\Users\Peruano Pinto\Documents\Codex\2026-07-09\necesito\work\claude-work-mcp"
.\scripts\register-claude.ps1
```

Manual equivalent:

```powershell
claude mcp add --scope user --transport stdio --env "WORK_MCP_CONFIG=C:\Users\Peruano Pinto\Documents\Codex\2026-07-09\necesito\work\claude-work-mcp\config\work-tools.local.json" claude-work-mcp -- node "C:\Users\Peruano Pinto\Documents\Codex\2026-07-09\necesito\work\claude-work-mcp\dist\server.js"
claude mcp list
```

If you prefer JSON config, copy `claude-code.mcp.json.example` into a Claude Code project as `.mcp.json`, then start Claude Code and approve the project MCP server.

## Register with Claude Code on Linux/macOS

```bash
cd /path/to/claude-work-mcp
npm install
npm run build
./scripts/register-claude.sh
```

## Configure your tools

Edit `config/work-tools.local.json`.

Add a direct API endpoint:

```json
{
  "id": "crm_lookup",
  "name": "CRM contact lookup",
  "method": "GET",
  "url": "https://api.example.com/contacts?email=${params.email}",
  "headers": {
    "Authorization": "Bearer ${env:CRM_API_TOKEN}"
  }
}
```

Then set the token before starting Claude Code:

```powershell
$env:CRM_API_TOKEN = "..."
```

Command execution and file writes are off by default. Turn them on only when you want Claude Code to make changes:

```json
{
  "allowWrite": true,
  "allowCommands": true,
  "commandAllowlist": [{ "command": "git" }, { "command": "npm" }]
}
```

## Suggested Claude prompt

```text
Use the claude-work-mcp MCP server. First call list_work_tools, then read_handoff. Work only inside the configured workspace. If you need to change files or run commands and the tool is disabled, tell me exactly what config change you need.
```

## Safety model

This server does not call arbitrary URLs. It only calls endpoints listed in config.

It does not access arbitrary filesystem paths. All workspace file tools stay inside `workspaceRoot`.

It does not run shell commands unless `allowCommands=true`, and even then only command names in `commandAllowlist`. Interpreter commands (`node`, `py`, `bash`, etc.) are additionally blocked from running with inline-eval flags (`-e`, `-c`, `--eval`, ...) even when allowlisted, since those flags bypass the `workspaceRoot` sandbox.

Single-file reads and writes also resolve symlinks and reject any target whose real path falls outside `workspaceRoot`, so a symlink planted inside the workspace cannot be used to read or write files elsewhere on disk.