DeepSeek_MCP — DeepSeek Worker for Claude Code (Python)

A local Python MCP server that lets real Claude Code delegate expensive, read-heavy repository work to DeepSeek V4 Pro over DeepSeek's Anthropic-compatible API. Claude stays the orchestrator, planner, editor, and final reviewer; DeepSeek is a subordinate worker with bounded, budgeted, compacted access to your files.

The parent Claude Code backend is not replaced — no ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN redirection. DeepSeek credentials are scoped to the Python MCP child process only.

Architecture

User
  ↓
Claude Code (real Claude — orchestrator / planner / editor / final reviewer)
  ↓ MCP stdio
Python deepseek-mcp child process  (src/deepseek_mcp/)
  │  ├─ deepseek_task / deepseek_review / deepseek_usage   (Claude-facing tools)
  │  ├─ internal worker loop: budget + timeout + iteration caps
  │  ├─ internal tools: repo_list, repo_search, repo_read, repo_stat,
  │  │                  git_diff, git_status, git_show,
  │  │                  fs_read, fs_glob, fs_grep,               (file tools)
  │  │                  fs_write, fs_edit, fs_notebook_edit,     (writes, opt-in)
  │  │                  fs_bash                                  (shell, opt-in)
  │  ├─ AccessPolicy: canonical-root containment, deny globs, .gitignore
  │  └─ 3 compaction layers: tool results → working memory → final response
  ↓ Anthropic-compatible API (api.deepseek.com/anthropic)
DeepSeek V4 Pro

• Claude-facing surface: exactly 3 MCP tools — deepseek_task, deepseek_review, deepseek_usage.

• Read-only by default: the original spec made the worker strictly read-only. Per the project owner's explicit decision (2026-08-23), the worker's internal toolset also includes file tools beyond the repository root and — when enabled in YAML — Write/Edit/NotebookEdit/Bash. All of it stays confined to allowed roots and bounded by budgets; see “Spec-pack deviation” and “Security/privacy model” below.

• Every worker response ends with a mandatory DeepSeek token-usage footer.

Related MCP server: DS Claude Haha MCP

What gets delegated

Good delegation candidates (read-heavy, repetitive, high-context):

• repository exploration and architecture mapping,

• reading many files / tracing call paths and dependencies,

• code search and evidence collection,

• large diff analysis and first-pass code review,

• log summarization.

What normally stays with Claude: planning, final architectural decisions, edits, final review, and security-sensitive judgment. Worker output is advisory — Claude verifies material findings (usually the highest-severity/highest-confidence ones) before acting on them.

Prerequisites

For DeepSeek_MCP itself:

• Python 3.11+ (built and tested on 3.12)

• uv (recommended package/environment manager; installed at build time)

• git on PATH (only for git_diff/git_status/git_show)

Separately, for use with Claude Code:

• Claude Code installed by its normal upstream method (its own runtime requirements are independent of this Python project)

• a DeepSeek API key (for deepseek_task / deepseek_review; deepseek_usage and MCP discovery work without one)

Installation

git clone <this-repository> DeepSeek_MCP
cd DeepSeek_MCP
uv sync        # creates .venv, installs the package + dev tools
uv build       # optional: builds dist/ sdist + wheel

Configure the DeepSeek key

The key is read from the environment variable named by provider.api_key_env (default DEEPSEEK_API_KEY). It is never stored in YAML, .mcp.json, or source.

Linux/macOS (persist in ~/.bashrc / ~/.zshrc):

export DEEPSEEK_API_KEY="sk-..."

Windows PowerShell:

setx DEEPSEEK_API_KEY "sk-..."

Never export DeepSeek credentials as the parent ANTHROPIC_AUTH_TOKEN or ANTHROPIC_BASE_URL — that would replace Claude itself.

Configure model and budget

Everything lives in config/deepseek-worker.yaml (set DEEPSEEK_CONFIG to point at another file if you like). Field-by-field:

Repository root resolution order (canonicalized before use): per-call repo_root arg (only if allow_repo_root_argument: true) → MCP roots when unambiguous → DEEPSEEK_REPO_ROOT → the MCP process working directory.

Connect to Claude Code

Option A — project .mcp.json

Copy the example and restart Claude Code:

cp .mcp.json.example .mcp.json

Example content (matches the built paths):

{
  "mcpServers": {
    "deepseek-worker": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "${CLAUDE_PROJECT_DIR:-.}", "run", "deepseek-mcp"],
      "env": {
        "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}",
        "DEEPSEEK_REPO_ROOT": "${CLAUDE_PROJECT_DIR:-.}",
        "DEEPSEEK_CONFIG": "${CLAUDE_PROJECT_DIR:-.}/config/deepseek-worker.yaml"
      }
    }
  }
}

Option B — claude mcp add

claude mcp add deepseek-worker \
  --scope user \
  --env DEEPSEEK_API_KEY \
  --env DEEPSEEK_CONFIG=/path/to/DeepSeek_MCP/config/deepseek-worker.yaml \
  -- uv run --directory /path/to/DeepSeek_MCP deepseek-mcp

(--env DEEPSEEK_API_KEY without a value passes the variable through from your shell.) (--env DEEPSEEK_REPO_ROOT=/path/to/your/repo \ for specific project)

Verify registration

claude mcp list
claude mcp get deepseek-worker

and inside Claude Code run /mcp — deepseek-worker should be listed as connected. The server also starts standalone: uv run deepseek-mcp (or uv run python -m deepseek_mcp).

Install global Claude instructions

GLOBAL_CLAUDE.md in this repository is a template of behavioral guidelines for Claude Code (delegation discipline: visible delegation notices, worker-return notices, treat-worker-output-as-evidence, budget awareness, …). For user-global behavior, merge the relevant content into your Claude Code user instructions file (commonly ~/.claude/CLAUDE.md, subject to current Claude Code behavior).

Merge, don't overwrite — copy only the sections you want; never replace your existing personal instructions wholesale.

Usage examples

Read this repo and map the request lifecycle. Delegate the repository scan to
DeepSeek Worker.

Review my working-tree diff. Use DeepSeek for the first-pass large diff review,
then validate the high-confidence findings yourself.

Find all call sites affected by changing FooConfig and summarize them before
making edits.

Per GLOBAL_CLAUDE.md, delegation is never silent. Before each call Claude shows a notice like:

↳ Delegating to DeepSeek Worker: repository-wide scan of auth flow to save Claude context.

and after it returns:

↳ DeepSeek Worker returned: 4 candidate call sites; I will verify the high-impact
ones before editing. Worker usage: 183,421 input / 12,874 output tokens.

Context and response compaction

The worker saves context in both directions:

Claude → delegates large read-heavy work → DeepSeek
Claude ← receives compact findings + evidence ← DeepSeek MCP

Three deterministic layers:

1. Bounded tool results — every repo/fs/git/basher tool result is truncated to compaction.max_tool_result_chars with an explicit omission marker before it re-enters DeepSeek's context.

2. Rolling working memory — when the message history estimate reaches worker_context_soft_limit_tokens, older messages are folded into one structured # Worker Working Memory message (objective, confirmed evidence with path:line-range, findings, open questions, files inspected, next reads). The most recent preserve_recent_messages stay verbatim. The hard limit blocks further API calls. Objectives and evidence identifiers survive repeated compactions.

3. Deterministic final compaction — the final DeepSeek answer is compacted server-side (a pure Python pass — no extra paid model call) to the final_target_chars for brief | normal | detailed, with per-mode finding/evidence caps, evidence deduplication, severity/confidence sorting for reviews, and explicit omission markers. final_hard_limit_chars always wins.

Raw DeepSeek transcripts are not returned to Claude by default. Example compact result:

## Worker result
Authentication is parsed in src/auth.py and verified by middleware before lookup.

## Key findings
1. [severity: high] [confidence: high] `src/auth.py:31-55` — token parsed without length check.

## Evidence
- `src/auth.py:31-55` — Bearer token split on first space; no bounds validation.
- `src/user.py:80-103` — user lookup occurs after middleware.

## Uncertainties
- Refresh-token path not traced.

## Suggested next checks
- Inspect `src/middleware/session.py` for the second validation site.

---
DeepSeek Worker Usage
run_id: ds_20260823_010203_abcd1234
model: deepseek-v4-pro
api_calls: 7
input_tokens: 183421
output_tokens: 12874
cache_read_tokens: 52210
cache_write_tokens: n/a
total_tokens: 196295
estimated_cost_usd: 0.091384
budget_status: ok

If a compaction marker says details were omitted, ask Claude to inspect the specific path:line evidence you actually need — don't raise every worker response size.

Token usage footer

Every deepseek_task / deepseek_review response ends with the footer above:

• run_id — one id per tool invocation; it covers all DeepSeek API calls inside that run,

• api_calls — successful provider responses that returned usage,

• input_tokens / output_tokens — aggregated provider-reported usage across the run,

• cache_read_tokens / cache_write_tokens — shown when the provider reports them (n/a otherwise),

• total_tokens — input_tokens + output_tokens (cache counters are not counted twice),

• estimated_cost_usd — from the YAML pricing snapshot; not authoritative billing,

• budget_status — ok, or stopped when a budget/timeout/error stopped the run.

deepseek_usage(scope="process" | "last_run") reports run/process totals plus the configured limits and pricing snapshot, and never calls DeepSeek.

Security / privacy model

• Repository content the worker reads is sent to the configured DeepSeek API. Review your organization's policies before using this on code you are not permitted to send to that provider.

• Local containment: every path passes a canonical-root check (Path.resolve() + containment — not string prefixes). .. traversal, absolute escape, and symlink escape are rejected. Access is confined to the repository root plus tools.extra_allowed_roots.

• Deny globs (.env*, *.pem, *.key, *credentials*, *secret*, .git/**, node_modules/**, dist/**, build/**) apply to reads and writes. This is a sensible default, not a perfect DLP system — the worker can still see other files you have not classified.

• Binary and oversized files are rejected/skipped.

• Git runs only through fixed argument arrays (asyncio.create_subprocess_exec, never a shell); fs_bash is the only arbitrary-command surface, and only when tools.allow_bash: true. Bash children get a validated cwd, bounded output, a timeout, and an environment with DEEPSEEK_API_KEY/ANTHROPIC_* stripped.

• Prompt injection: the worker system prompt instructs DeepSeek to treat repository text as data, never to follow instructions found in source files, and never to request secrets. Claude still treats worker output as untrusted evidence.

• Logs go to stderr only; API keys and headers are never logged.

Spec-pack deviation (2026-08-23): the project owner explicitly chose “Full toolset + spec override”. The worker therefore includes file tools beyond the repository root and, when enabled, Write/Edit/NotebookEdit/Bash tools. This means the original acceptance items “Worker cannot write repository files” and “Arbitrary shell is unavailable” are not satisfied by design. Set tools.allow_writes: false and tools.allow_bash: false to restore a strictly read-only worker; allow_file_tools: false restricts access to the repository root only.

Troubleshooting

• Worker not visible in /mcp — check claude mcp list / claude mcp get deepseek-worker; confirm the .mcp.json paths and that uv run deepseek-mcp starts from the project directory.

• Missing DEEPSEEK_API_KEY — deepseek_task/deepseek_review return a typed error naming the variable; deepseek_usage still works. Export the key (see above).

• Invalid YAML — the server refuses to start and prints the specific validation problem to stderr (unsupported version, bad URL, limit ordering, …).

• API 401/403 — wrong/unauthorized key, or key missing from the MCP server env.

• API 429 / rate limit — the run stops with a provider error result and a footer; wait and retry later rather than spamming retries.

• Request timeout — raise provider.request_timeout_ms, or split the task.

• Budget stop — the result is partial by design (budget_status: stopped + reason + working memory). Use the partial evidence; don't silently retry with a bigger budget.

• Path denied — the file matches a deny glob, is git-ignored, or lies outside allowed roots; adjust deny_globs / extra_allowed_roots deliberately.

• MCP output too large — worker results are capped by compaction limits; keep them concise rather than raising Claude Code's MAX_MCP_OUTPUT_TOKENS.

• Windows path issues — use setx for env vars; the server uses pathlib and fixed subprocess argv, but deny globs are case-sensitive.

• Debug logs — set logging.level: debug in the YAML (stderr only, never stdout).

Development

uv run pytest                             # full suite (fake DeepSeek client, no paid calls)
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv build

MCP smoke tests:

uv run pytest tests/test_mcp.py           # tool list/schemas + in-memory MCP calls
uv run pytest tests/test_mcp.py::test_stdio_startup_smoke   # real stdio subprocess

Optional real-API smoke test (only when a key is set; a few API calls, ~cents):

DEEPSEEK_API_KEY=sk-... uv run python scripts/real_api_smoke.py
DEEPSEEK_API_KEY=sk-... uv run python scripts/real_api_smoke.py /path/to/your/repo

Updating the model or pricing

Edit config/deepseek-worker.yaml (model name, budgets, compaction, pricing snapshot) and restart the MCP server / Claude Code session — there is no live config reload in v1. Pricing changes over time; update pricing.per_million_tokens and snapshot_date from DeepSeek's pricing page.

Uninstall

1. Remove the MCP registration: claude mcp remove deepseek-worker, or delete the deepseek-worker entry from your project .mcp.json (whichever you used).

2. Remove/merge back any global CLAUDE.md instructions you copied from GLOBAL_CLAUDE.md.

3. Delete the repository directory if desired.

4. Remove any shell/profile DEEPSEEK_API_KEY export dedicated to this project.

5. Optionally revoke/delete the DeepSeek API key in the provider console.

Do not uninstall Claude Code itself unless you explicitly want to.

Limitations

• Worker output can be wrong — Claude must validate material claims (especially path:line citations) before acting on them.

• Token/cost budgets are per worker run; a single final provider response may slightly cross a cumulative threshold (no further calls are allowed afterward).

• estimated_cost_usd is a snapshot-based estimate; provider billing is authoritative.

• Very large, binary, denied, or git-ignored files are skipped or rejected by design.

• The default config enables write/bash worker tools (spec-pack deviation above); disable them in YAML if you want the strictly read-only behavior.

• DeepSeek context compaction uses a conservative local char-based token estimate for triggering only; displayed token counts always come from provider usage.

References

• DeepSeek API docs — https://api-docs.deepseek.com/

• DeepSeek Anthropic-compatible API — https://api-docs.deepseek.com/guides/anthropic_api/

• Claude Code MCP docs — https://code.claude.com/docs/en/mcp

• MCP Python SDK — https://github.com/modelcontextprotocol/python-sdk

• Behavioral inspiration — https://github.com/multica-ai/andrej-karpathy-skills