scribe-mcp

An MCP server that delegates bulk file reading and doc/boilerplate writing from Claude to a cheaper, OpenAI-compatible model — saving 60–90 % of tokens on tasks that don't require frontier-level reasoning.

Claude sees mcp__scribe__bulk_read like any other MCP tool and routes heavy reading/writing tasks to a cheaper model automatically.

Table of Contents

• Install
  • Claude Code (CLI)
  • Claude Code (manual)
  • Tool search and alwaysLoad
• Configuration
• Switching providers
• Tools
  • mcp__scribe__bulk_read
  • mcp__scribe__write_docs
  • mcp__scribe__write_boilerplate
• Benchmark
• Develop
• License

Install

Claude Code (CLI)

Project-level (saved to .mcp.json, shared with the team):

claude mcp add scribe -s project -e SCRIBE_API_KEY=your-api-key-here -- npx -y scribe-mcp

User-level (saved to ~/.claude.json, available across all your projects):

claude mcp add scribe -s user -e SCRIBE_API_KEY=your-api-key-here -- npx -y scribe-mcp

To pass additional variables, repeat the -e flag:

claude mcp add scribe -s user \
  -e SCRIBE_API_KEY=your-api-key-here \
  -e SCRIBE_BASE_URL=https://openrouter.ai/api/v1 \
  -e SCRIBE_MODEL=deepseek/deepseek-chat-v3-0324 \
  -- npx -y scribe-mcp

Recommended: after running the command above, add "alwaysLoad": true to the generated server entry so Claude always sees Scribe's tools without a prior tool-search step. See Tool search and alwaysLoad.

Claude Code (manual)

Add to ~/.claude.json:

{
  "mcpServers": {
    "scribe": {
      "command": "npx",
      "args": ["-y", "scribe-mcp"],
      "env": {
        "SCRIBE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Tool search and alwaysLoad

By default, Claude Code defers MCP tool schemas (only loading them on demand via a search step). With many MCP servers active this saves context, but it also means Claude does not see scribe's tool descriptions at session start and may default to its built-in Read / Explore tools instead.

To make scribe always visible in the tool catalog, set alwaysLoad: true on the server entry in .mcp.json:

{
  "mcpServers": {
    "scribe": {
      "command": "npx",
      "args": ["-y", "scribe-mcp"],
      "env": { "SCRIBE_API_KEY": "${SCRIBE_API_KEY}" },
      "alwaysLoad": true
    }
  }
}

Requires Claude Code v2.1.121 or later. See the Claude Code MCP docs for the full mechanism.

The server already ships with built-in usage instructions covering when to delegate and when not to (architectural decisions, debugging, safety-critical code, precise-line-number edits). A separate CLAUDE.md snippet is only needed if you want project-specific overrides.

Configuration

All configuration is via environment variables (set in the env block above):

| Variable | Default | Description | |---|---|---| | SCRIBE_API_KEY | — required | API key for the LLM provider | | SCRIBE_BASE_URL | https://api.minimax.io/v1 | OpenAI-compatible endpoint | | SCRIBE_MODEL | MiniMax-Text-01 | Model identifier | | SCRIBE_MAX_TOKENS | 8192 | Max tokens per response | | SCRIBE_REASONING | false | Enable reasoning/thinking mode (off by default) | | SCRIBE_WORKSPACE_ROOT | — optional | Restrict file access to this directory | | SCRIBE_LOG_LEVEL | info | debug | info | warn | error |

Switching providers

Any OpenAI-compatible endpoint works. Just change SCRIBE_BASE_URL and SCRIBE_MODEL:

OpenRouter (DeepSeek V3):

"env": {
  "SCRIBE_API_KEY": "sk-or-...",
  "SCRIBE_BASE_URL": "https://openrouter.ai/api/v1",
  "SCRIBE_MODEL": "deepseek/deepseek-chat-v3-0324"
}

DeepSeek direct:

"env": {
  "SCRIBE_API_KEY": "sk-...",
  "SCRIBE_BASE_URL": "https://api.deepseek.com/v1",
  "SCRIBE_MODEL": "deepseek-chat"
}

Groq (Llama 3.3 70B):

"env": {
  "SCRIBE_API_KEY": "gsk_...",
  "SCRIBE_BASE_URL": "https://api.groq.com/openai/v1",
  "SCRIBE_MODEL": "llama-3.3-70b-versatile"
}

Tools

mcp__scribe__bulk_read

Reads multiple files or glob patterns and returns a targeted summary or answer.

| Parameter | Type | Default | Description | |---|---|---|---| | paths | string[] | required | File paths or glob patterns | | question | string | required | What to extract or summarise | | max_files | number | 50 | Maximum files to read |

When to use: reading ≥ 3 files, or any file > 400 lines, where the task is summarisation, search, or explanation — not editing.

mcp__scribe__write_docs

Generates documentation (README, JSDoc, module comments, etc.) and writes it to disk.

When to use: generating documentation that doesn't require frontier-level reasoning (READMEs, JSDoc, module comments).

| Parameter | Type | Default | Description | |---|---|---|---| | target_path | string | required | Output file path | | instruction | string | required | What to generate | | context_paths | string[] | — | Source files to read for context | | preview | boolean | false | Return content without writing | | append | boolean | false | Append instead of overwrite |

mcp__scribe__write_boilerplate

Generates boilerplate code (tests, types, CRUD, fixtures) matching your project's style.

When to use: repetitive code (tests, types, CRUD handlers, fixtures). Pass 1–2 reference_paths so output matches existing style.

| Parameter | Type | Default | Description | |---|---|---|---| | target_path | string | required | Output file path | | spec | string | required | Description of what to generate | | reference_paths | string[] | — | Existing files for style reference | | preview | boolean | false | Return content without writing | | append | boolean | false | Append instead of overwrite |

Benchmark

Scribe MCP was benchmarked against Claude Code alone and Serena on a real summarisation task. Key findings:

• −41 % output tokens vs Claude Only
• −13 % total cost vs Claude Only, with no setup required
• Serena achieves the lowest cost overall, but requires a per-repository onboarding step

→ See the full benchmark results for token-by-token details.

Develop

git clone https://github.com/cicoub13/scribe-mcp
cd scribe-mcp
npm install
npm run build

# Run locally (set env vars first)
export SCRIBE_API_KEY=your-key
node dist/index.js

Available scripts:

| Command | Description | |---|---| | npm run build | Compile TypeScript | | npm run dev | Run with tsx (no compile step) | | npm run lint | ESLint | | npm run lint:fix | ESLint with auto-fix | | npm run format | Prettier | | npm test | Vitest unit tests | | npm run test:coverage | Tests with coverage report | | node scripts/smoke.mjs | Smoke test (requires npm run build first) |

Test interactively with MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

License

MIT