deepseek-claude-code-worker-mcp

DeepSeek Claude Code Worker MCP

Skill by ara.so — MCP Skills collection.

Overview

DeepSeek Claude Code Worker MCP is a coding-worker server for Codex Desktop that delegates expensive code reading, editing, and checking to DeepSeek V4 through Claude Code. The workflow is: Codex plans and reviews, DeepSeek V4 executes implementation work in isolated background jobs. This saves Codex main-thread tokens by 40-60% on suitable coding tasks.

Key concept: This is not a standalone DeepSeek client. It includes a claude-deepseek launcher that runs the local Claude Code CLI against DeepSeek's Anthropic-compatible endpoint.

Current beta: v0.3.20-beta.38

Installation

GitHub (no global install)

Add to your MCP config (~/.codex/config.toml or similar):

{
  "mcpServers": {
    "deepseek-code-worker": {
      "command": "npx",
      "args": [
        "github:louchi1984-coder/deepseek-claude-code-worker-mcp#v0.3.20-beta.38"
      ]
    }
  }
}

Source mode (recommended for development)

git clone https://github.com/louchi1984-coder/deepseek-claude-code-worker-mcp.git
cd deepseek-claude-code-worker-mcp
npm install
npm run mcp:setup
npm run mcp:doctor

Source-mode MCP config:

{
  "mcpServers": {
    "deepseek-code-worker": {
      "command": "node",
      "args": ["/absolute/path/to/deepseek-claude-code-worker-mcp/src/deepseek-worker-mcp.mjs"]
    }
  }
}

Quick check without installing

npx github:louchi1984-coder/deepseek-claude-code-worker-mcp#v0.3.20-beta.38 --doctor

Expected output:

{
  "server_version": "0.3.20-beta.38",
  "ok": true
}

Requirements

• Node.js 20+
• Claude Code CLI (@anthropic-ai/claude-code)
• DeepSeek API key
• macOS / Linux (Windows is best-effort)

Environment variables

• DEEPSEEK_API_KEY or ~/.codex/secrets/deepseek_api_key
• ANTHROPIC_AUTH_TOKEN (for Claude Code)
• DEEPSEEK_API_KEY_FILE (alternative key location)
• CLAUDE_BIN (custom Claude Code CLI path)

Setup can interactively install Claude Code and prompt for DeepSeek key if missing.

Core Tools

deepseek_start_implementation

Starts a background coding job. Returns job_id immediately.

// Minimal start
{
  "name": "deepseek_start_implementation",
  "arguments": {
    "cwd": "/absolute/project/path",
    "task": "Add error handling to the authentication module"
  }
}

// With boundaries and validation
{
  "name": "deepseek_start_implementation",
  "arguments": {
    "cwd": "/home/user/myproject",
    "task": "Implement rate limiting middleware with Redis backend",
    "allowed_dirs": ["src/middleware", "src/lib/redis"],
    "forbidden_paths": ["src/config/secrets.json", ".env"],
    "generated_paths": ["docs/RATE_LIMIT_EVAL.md"],
    "validation_commands": [
      "npm test -- middleware.test.js",
      "npm run lint src/middleware"
    ],
    "use_case": "simple_agent_task",
    "worker_profile": "scoped_patch"
  }
}

// Complex reasoning task
{
  "name": "deepseek_start_implementation",
  "arguments": {
    "cwd": "/home/user/complex-app",
    "task": "Debug and fix the race condition in the WebSocket message queue",
    "use_case": "debug_loop",
    "allowed_dirs": ["src/websocket", "src/queue", "tests"],
    "validation_commands": ["npm run test:integration:ws"]
  }
}

Returns:

{
  "job_id": "dsw_abc123",
  "status": "running",
  "cwd": "/home/user/myproject",
  "started_at": "2026-06-01T10:30:00Z"
}

deepseek_get_job

Reads compact job status. Does not include logs/events/diffs by default.

// Basic status check
{
  "name": "deepseek_get_job",
  "arguments": {
    "job_id": "dsw_abc123"
  }
}

// With full evidence (use sparingly)
{
  "name": "deepseek_get_job",
  "arguments": {
    "job_id": "dsw_abc123",
    "include_logs": true,
    "include_events": true,
    "include_diff": true
  }
}

Returns (compact):

{
  "job_id": "dsw_abc123",
  "status": "completed",
  "exit_code": 0,
  "files_changed": ["src/middleware/rateLimiter.js", "tests/middleware.test.js"],
  "checks": {
    "npm test -- middleware.test.js": {"exit_code": 0, "stderr": ""},
    "npm run lint src/middleware": {"exit_code": 0, "stderr": ""}
  },
  "policy": {
    "out_of_scope": [],
    "forbidden_touched": [],
    "generated_changed": ["docs/RATE_LIMIT_EVAL.md"]
  },
  "tool_activity": {
    "total_actions": 8,
    "bash": 3,
    "edit": 2,
    "write": 1,
    "read": 2
  }
}

deepseek_tail_job

Reads compact status with optional logs. Similar to get_job but designed for progress checks.

{
  "name": "deepseek_tail_job",
  "arguments": {
    "job_id": "dsw_abc123",
    "include_logs": false  // default
  }
}

deepseek_wait_for_job

Short observation window (default 30s). Does NOT kill the worker on timeout. Use for quick status updates, not as a main loop.

{
  "name": "deepseek_wait_for_job",
  "arguments": {
    "job_id": "dsw_abc123",
    "timeout_sec": 30
  }
}

deepseek_cancel_job

Requests job cancellation.

{
  "name": "deepseek_cancel_job",
  "arguments": {
    "job_id": "dsw_abc123"
  }
}

deepseek_implement_in_workspace

Synchronous mode for tiny edits. Blocks until complete.

{
  "name": "deepseek_implement_in_workspace",
  "arguments": {
    "cwd": "/home/user/myproject",
    "task": "Fix typo in README.md line 42",
    "use_case": "fast_patch"
  }
}

Use Cases and Model Selection

The MCP chooses DeepSeek model and reasoning effort based on use_case. Goal: save Codex main-thread tokens, not DeepSeek tokens.

use_case	Default model	effort	Best for
auto	deepseek-v4-flash	max	general implementation
fast_patch	deepseek-v4-flash	high	small patches
simple_agent_task	deepseek-v4-flash	high	simple agentic coding
scaffold_or_tests	deepseek-v4-flash	high	scaffolding, glue, tests
debug_loop	deepseek-v4-pro[1m]	max	reproduce, locate, fix, validate
agentic_coding	deepseek-v4-pro[1m]	max	multi-step implementation
complex_reasoning	deepseek-v4-pro[1m]	max	architecture, hard logic
long_context_codebase	deepseek-v4-pro[1m]	max	broad codebase work
docs_generation	deepseek-v4-pro[1m]	high	documentation

Selection rules:

• Use auto by default
• Use fast_patch for obviously tiny edits
• Use scaffold_or_tests for tests, scaffolding, glue code
• Use debug_loop for reproduce/locate/fix/validate workflows
• Use Pro[1m] presets for cross-file implementation, complex logic, or broad context
• Don't default to Pro[1m] just because it sounds stronger

Override with explicit model, thinking, or reasoning_effort if needed.

Worker Profiles

Control permission scope with worker_profile:

• default: Standard Claude Code scoped permissions
• scoped_patch: Tightly scoped, narrow allowed_dirs
• safe_readonly: Restricted bash, read-only operations (use with safety_mode: "safe")

Safety and Permissions

Not a sandbox. Guardrails:

• Temporary Claude Code dontAsk settings per worker
• PreToolUse hook blocks clearly dangerous Bash and forbidden paths
• Hooks log compact action summaries
• Final snapshot policy checks report out-of-scope changes

Default: safety_mode: "permissive" (Bash allowed except dangerous commands)

Strict: safety_mode: "safe" (Bash restricted to read-only and explicit checks)

bypassPermissions: disabled by default. Keep it off unless you add external sandboxing.

Path boundaries

• allowed_dirs: Target directories for implementation
• forbidden_paths: Hard failure if touched
• generated_paths: Validation/eval outputs; reported as generated_changed, not out-of-scope

v0.3.20-beta.38 principle: Report actions as facts, don't auto-fail. Out-of-scope changes are reported; forbidden_paths remains a hard failure.

Token-Saving Discipline

To maximize Codex token savings:

1. Narrow task scope: One goal, clear boundaries, explicit validation
2. Minimal context: Don't read whole codebase before delegating
3. Compact status: Avoid logs/events/diffs while job is running
4. Selective review: After completion, review only files_changed, key ranges, checks, risks
5. Project brief pattern:

Project brief:
- Project: <one-line goal>
- Current slice: <module/feature>
- Task: <single implementation goal>
- Boundaries: <allowed_dirs>
- Generated outputs: <eval reports>
- Do not touch: <forbidden_paths>
- Validate: <commands>
- Previous result: <job_id + status + diff/check summary>

6. Follow-up workers: Pass only necessary previous-result summary, not full history

Configuration Examples

Scoped patch with validation

{
  "cwd": "/home/user/app",
  "task": "Add input sanitization to user registration endpoint",
  "use_case": "simple_agent_task",
  "worker_profile": "scoped_patch",
  "allowed_dirs": ["src/routes/auth", "src/lib/sanitize"],
  "forbidden_paths": ["src/config", ".env", "secrets"],
  "validation_commands": [
    "npm test -- auth.test.js",
    "npm run security-scan src/routes/auth"
  ],
  "safety_mode": "permissive"
}

Debug loop with Pro model

{
  "cwd": "/home/user/complex-service",
  "task": "Reproduce and fix the memory leak in the background job processor",
  "use_case": "debug_loop",  // Uses deepseek-v4-pro[1m]
  "allowed_dirs": ["src/jobs", "src/workers", "tests/integration"],
  "validation_commands": [
    "npm run test:memory-profile",
    "npm run test:jobs"
  ],
  "generated_paths": ["logs/memory_profile.txt"]
}

Documentation generation

{
  "cwd": "/home/user/library",
  "task": "Generate API documentation for the public interfaces",
  "use_case": "docs_generation",
  "allowed_dirs": ["docs/api", "src"],
  "generated_paths": ["docs/api/generated"],
  "validation_commands": ["npm run docs:validate"]
}

Workflow Patterns

Pattern 1: Start and check later

// 1. Start job
const startResult = await deepseek_start_implementation({
  cwd: "/home/user/project",
  task: "Implement user profile caching with Redis"
});

// 2. Do other Codex work...

// 3. Check status when needed
const status = await deepseek_get_job({
  job_id: startResult.job_id
});

// 4. If completed, review changes
if (status.status === "completed") {
  // Review status.files_changed, status.checks, status.policy
}

Pattern 2: Follow-up worker

// First job failed validation
const firstJob = await deepseek_get_job({ job_id: "dsw_first123" });
// status.checks shows test failure

// Start follow-up with context
await deepseek_start_implementation({
  cwd: "/home/user/project",
  task: `Fix the test failure from previous job dsw_first123.
Previous result: Tests failed with 'TypeError: Cannot read property id of undefined'.
Fix the null check in src/handlers/profile.js and ensure all tests pass.`,
  use_case: "debug_loop",
  allowed_dirs: ["src/handlers", "tests"],
  validation_commands: ["npm test -- profile.test.js"]
});

Pattern 3: Tiny synchronous edit

// For obviously tiny changes, use synchronous mode
const result = await deepseek_implement_in_workspace({
  cwd: "/home/user/project",
  task: "Change the default port from 3000 to 8080 in config.js",
  use_case: "fast_patch"
});
// Blocks until complete

Setup and Verification

Initial setup

npm run mcp:setup

Interactively installs Claude Code if missing and prompts for DeepSeek key.

Health check

npm run mcp:doctor

Expected output:

{
  "server_version": "0.3.20-beta.38",
  "claude_code_installed": true,
  "claude_code_version": "1.2.3",
  "deepseek_key_configured": true,
  "ok": true
}

Common issue: claude_code_version failed but claude command exists.

Cause: Wrapper script or stale shim intercepts claude --version.

Fix: Fix Claude Code install or set CLAUDE_BIN to real executable, then rerun doctor.

Smoke tests

npm run mcp:smoke:stream      # Stream processing
npm run mcp:smoke:permission  # Permission hooks
npm run mcp:smoke:restore     # Snapshot restore
npm run mcp:smoke             # Full real worker test (requires CLI + key)

Troubleshooting

Worker seems stuck

DeepSeek V4 Pro can spend ~10 minutes in one continuous thinking segment on complex tasks. This is not cumulative job runtime — it's a single reasoning phase.

• Don't assume quiet = stuck
• Don't poll logs while running
• Check compact status only when you need facts
• Use deepseek_get_job without include_logs for quick checks

Job completed but validation failed

const status = await deepseek_get_job({
  job_id: "dsw_abc123",
  include_logs: true  // Get validation output
});

// Check status.checks for failure details
// Example:
// status.checks["npm test"] = { exit_code: 1, stderr: "..." }

Start a follow-up worker with the failure context.

Out-of-scope changes reported

Version 0.3.20-beta.38 reports out-of-scope changes as facts, not automatic failures (unless forbidden_paths touched).

const status = await deepseek_get_job({ job_id: "dsw_abc123" });

if (status.policy.out_of_scope.length > 0) {
  // Review: Are these changes acceptable?
  // status.policy.out_of_scope = ["src/other-module/file.js"]
}

if (status.policy.forbidden_touched.length > 0) {
  // Hard failure: Forbidden paths were touched
  // This is a real error
}

Claude Code version check fails

If doctor reports claude_code_version as failed:

1. Check which claude — is it a wrapper?
2. Run claude --version manually — does it output a version?
3. Set CLAUDE_BIN to the real Claude Code executable:

export CLAUDE_BIN="/usr/local/bin/claude-code"
npm run mcp:doctor

Permission denied errors

• Ensure allowed_dirs covers the target files
• Check that forbidden_paths doesn't block necessary files
• Use generated_paths for validation outputs
• Consider worker_profile: "scoped_patch" for tight scope

DeepSeek API key not found

Setup looks for key in:

1. DEEPSEEK_API_KEY env var
2. ~/.codex/secrets/deepseek_api_key file
3. DEEPSEEK_API_KEY_FILE env var (custom path)

Set one of these or run npm run mcp:setup for interactive prompt.

Best Practices

1. Start with narrow scope: Single module, clear boundaries
2. Use appropriate use_case: Don't over-provision (Pro for everything) or under-provision (flash for complex tasks)
3. Validate explicitly: Include validation_commands for automated checks
4. Review after completion: Check files_changed, checks, policy before accepting
5. One worker per task: Don't start multiple workers for the same implementation
6. Compact status while running: Avoid logs/events/diffs until terminal status
7. Follow-up context: Pass previous job id + terminal status + relevant summary, not full history
8. Generated outputs: Use generated_paths for eval reports, not allowed_dirs widening

API Summary

Tool	Purpose	Blocking
deepseek_start_implementation	Start background job	No
deepseek_get_job	Get status	No
deepseek_tail_job	Get status with optional logs	No
deepseek_wait_for_job	Short observation window	No (doesn't kill)
deepseek_cancel_job	Cancel job	No
deepseek_implement_in_workspace	Synchronous implementation	Yes

Current Status

Beta v0.3.20-beta.38. Suitable for internal projects and early adopters. Not yet published to npm registry.