deepseek-mcp

一个 MCP 服务器，让 Claude Code 可以将一个有限范围的仓库工作单元委托给 DeepSeek 作为本地子代理。

Claude 仍然是编排者：它决定范围、架构和正确性。DeepSeek 是执行工人，负责处理 token 密集的部分——探索仓库、进行常规或重复性更改、运行测试——在单个授权工作区内，并受硬性预算约束。

关键在于避免为同一上下文支付两次费用。如果 Claude 读取了一个子系统，然后 DeepSeek 又读取一次，那就没有节省任何东西；因此，委托决策应该在广泛读取之前做出。

需要 Python 3.11+ 和 DeepSeek API 密钥。一个运行时依赖：MCP SDK。其他一切都是标准库。ripgrep 在存在时用于搜索，不存在时使用纯 Python 扫描。

1. 安装

该包尚未发布到 PyPI，因此请从检出中安装。全局安装一次——它不是项目依赖，并且适用于每个仓库。

git clone https://github.com/giaminhgist/DeepSeek_MCP.git
cd DeepSeek_MCP

uv tool install .          # recommended: isolated, and puts deepseek-mcp on PATH
# or
pipx install .
# or, into the current environment
pip install .

确认控制台脚本可解析：

deepseek-mcp --version     # -> deepseek-mcp 0.1.0

如果找不到命令，则安装目录不在你的 PATH 中。使用 uv 时，运行 uv tool update-shell 并打开一个新 shell。

deepseek-mcp 不带参数时会在 stdio 上启动 MCP 服务器。这就是 Claude Code 运行的内容；你通常不会自己调用它。

Related MCP server: claude-code

2. 设置 API 密钥

从 https://platform.deepseek.com/ 获取密钥。切勿将其放入项目仓库中。 从你的 shell 配置文件中导出：

export DEEPSEEK_API_KEY="sk-your-key-here"     # ~/.bashrc, ~/.zshrc, …

# Windows PowerShell
setx DEEPSEEK_API_KEY "sk-your-key-here"

然后检查服务器能否看到它：

deepseek-mcp --check       # prints a health report as JSON; exits 1 if unusable

--check 在密钥可读时打印 "mode": "enabled" 和 "status": "ok"。密钥本身永远不会出现在报告中。

支持三种密钥来源，按优先级顺序：

1. 服务器环境中的 DEEPSEEK_MCP_API_KEY 或 DEEPSEEK_API_KEY。

2. 用户配置文件中的 api_key_env，指定要读取的不同环境变量。

3. 用户配置文件中的 api_key——接受，但不鼓励，并且会产生启动警告，因为它将密钥放在磁盘上。

其他一切都是可选的；请参阅 配置参考。唯一值得提前知道的另一个变量是 DEEPSEEK_MCP_WORKSPACE，它固定授权的项目根目录，而不是自动发现它（请参阅 工作区）。

3. 将服务器添加到 Claude Code

如果 DEEPSEEK_API_KEY 已经在 Claude Code 继承的环境中导出：

claude mcp add deepseek --scope user -- deepseek-mcp

如果没有——例如桌面启动不读取你的 shell 配置文件——请显式传递：

claude mcp add deepseek --scope user -e DEEPSEEK_API_KEY=sk-your-key-here -- deepseek-mcp

--scope user 为每个项目注册它。使用 --scope local 仅用于当前项目。

等效的手写配置：

{
  "mcpServers": {
    "deepseek": {
      "command": "deepseek-mcp",
      "env": {
        "DEEPSEEK_API_KEY": "sk-your-key-here"
      }
    }
  }
}

当密钥已在继承的环境中时，完全省略 env 块。不要将密钥提交到任何仓库文件中。

4. 验证连接

claude mcp list            # deepseek should be listed and connected

然后，在 Claude Code 内部：

• 运行 /mcp——deepseek 应该出现并带有两个工具；

• 让 Claude 调用 deepseek_health。正常工作的服务器会回答 status: "ok"、mode: "enabled"、解析的工作区根目录、启用的功能以及预算限制。

如果没有配置密钥，服务器仍然启动并仍然回答 deepseek_health——报告 status: "error"、mode: "disabled"——因此可以从 Claude Code 内部诊断问题。在该状态下它不执行任何工作。

5. 故障排除

日志以 event key=value 记录的形式输出到 stderr，绝不会输出到 stdout。使用 DEEPSEEK_MCP_LOG_LEVEL=DEBUG 提高详细程度，或使用 DEEPSEEK_MCP_LOG_FILE=/absolute/path.log 将其发送到文件。

工具表面

两个工具，刻意为之。

deepseek_health

配置和健康：状态、模型、授权的 workspace 根目录及其解析方式、启用的功能以及预算限制。无秘密。使用它来确认工作进程可用，并在发送委托之前确定委托的规模。

delegate_to_deepseek

一个有限范围的工作单元，作为结构化契约而不是散文块：

{
  "objective": "Treat a None row as invalid and cover it with a test.",
  "scope": ["src/importer/**", "tests/importer/**"],
  "constraints": ["Do not change the public response schema."],
  "acceptance_criteria": ["validate_row(None) returns False."],
  "verification": [["pytest", "tests/importer", "-q"]],
  "mode": "write"
}

然后工作进程自行循环——glob、grep、读取、编辑、运行、修复——并返回紧凑的结果，而不是转录：

{
  "status": "completed",
  "summary": "Treated a None row as invalid and added a regression test.",
  "changed_files": ["src/importer/validate.py"],
  "created_files": ["tests/importer/test_none.py"],
  "deleted_files": [],
  "inspected_files": ["src/importer/__init__.py"],
  "verification": [
    {"argv": ["pytest", "tests/importer", "-q"], "exit_code": 0, "summary": "24 passed"}
  ],
  "warnings": [],
  "unresolved": [],
  "assumptions": [],
  "diff_stat": " src/importer/validate.py | 3 ++-",
  "metrics": {
    "turns": 7, "tool_calls": 12, "prompt_tokens": 18400,
    "completion_tokens": 2100, "duration_seconds": 41.2,
    "files_read": 4, "files_changed": 2, "compactions": 0
  }
}

状态：completed、partial、blocked、failed、budget_exceeded、disabled。预期失败——错误配置、被拒绝的路径、被拒绝的命令、耗尽的预算、提供者错误——都以这些状态之一返回并附有原因。Python 回溯永远不会。

模式只会收窄，不会放宽

模式与服务器配置的功能相交。请求超出服务器授予范围的请求在任何 API 调用之前被拒绝——它永远不能放宽策略。

工作进程不被信任的内容

结果中有两件事不来自模型：

• 更改文件列表 来自监视工具以及运行前快照的 git status 比较，因此用户预先存在的未提交编辑永远不会被报告为工作进程的工作。

• 状态。 如果请求的验证从未运行或退出非零，则声称的 completed 会被降级为 partial。failed 和 budget_exceeded 是服务器的裁决，工作进程根本无法声称。

无论如何都要验证。git status --short、git diff --stat，然后按风险比例读取更改的块。completed 是声明，不是证明。

预算

每次委托都有界限，运行会以结构化原因停止，而不是超限：轮次（24）、工具调用（80）、墙钟时间（15 分钟）、每次工具调用的输出（20,000 字符）、Read 窗口（250 行）、Grep 匹配（100）、Glob 路径（300）以及估计的活动上下文（96,000 个 token）。

上下文被视为预算资源，而不是不断增长的转录。超过阈值时，旧工具负载被替换为来自确定性执行账本的单行条目；如果这还不够，则丢弃整个旧轮次，因为账本仍然记录它们做了什么。系统提示、原始任务契约、最近的轮次和账本始终保留。永远不会花费额外的模型调用来总结，如果工作进程需要被驱逐的细节，它会再次读取文件。

所有限制都是可配置的，并由 deepseek_health 报告。

配置参考

标记为 保留 的设置会在启动时验证，但尚未使用。

优先级

环境变量 > 用户配置文件 > 内置默认值

缺失、格式错误或矛盾的设置是错误。服务器不会回退到更广泛的工作区或更宽松的策略。

如果配置加载失败，进程仍然启动并仍然回答 deepseek_health，但报告 status: "error"、mode: "disabled"，并且不执行任何工作。运行 deepseek-mcp --check 在命令行上查看相同的报告。

配置文件位置

用户配置文件位于任何项目之外：

DEEPSEEK_MCP_CONFIG 覆盖路径。如果设置了它且文件不存在，启动会失败，而不是静默使用默认值。默认位置缺少配置文件是可以的；空文件是可以的；未知键是错误。

配置文件模式

每个键都是可选的。

{
  "model": "deepseek-chat",
  "base_url": "https://api.deepseek.com/v1",
  "api_key_env": "DEEPSEEK_API_KEY",
  "workspace": "/absolute/path/to/project",
  "tools": {
    "enabled": ["Read", "Glob", "Grep", "Edit", "Write", "Run"],
    "max_write_bytes": 2000000,
    "allow_secret_paths": false,
    "secret_path_exceptions": []
  },
  "provider": {
    "timeout_seconds": 120,
    "max_retries": 3,
    "retry_base_delay": 0.5,
    "retry_max_delay": 8.0,
    "temperature": 0.0,
    "max_output_tokens": 4096
  },
  "budgets": {
    "max_turns": 24,
    "max_tool_calls": 80,
    "max_wall_seconds": 900,
    "max_tool_output_chars": 20000,
    "read_window_lines": 250,
    "max_grep_matches": 100,
    "max_glob_paths": 300,
    "max_context_tokens": 96000,
    "compaction_threshold_ratio": 0.7
  },
  "commands": {
    "default_timeout_seconds": 120,
    "max_timeout_seconds": 600,
    "extra_denied_executables": [],
    "extra_allowed_executables": [],
    "allow_unsafe_shell": false
  },
  "logging": { "level": "INFO", "file": null, "log_task_text": false },
  "debug": false
}

此处接受 api_key 键，但不鼓励：它将密钥放在磁盘上并产生启动警告。优先使用 api_key_env，它指定要读取的环境变量。

凭据和端点

没有 API 密钥就无法工作：启动时会报告服务器已禁用。

工作区

未显式指定工作区时，将从进程工作目录开始逐级向上查找 .git、.hg、.svn、pyproject.toml、package.json、go.mod 或 Cargo.toml，以发现根目录。如果都没有找到，则使用工作目录本身，并记录一条警告。

显式指定的工作区如果缺失、不可读、不是目录、是相对路径，或者是文件系统根目录，都会导致启动错误。它绝不会降级为工作目录。服务器不必位于你的项目内部，它也绝不会通过修改项目来激活自身。

工具

默认启用的工具是除 NotebookEdit 之外的所有工具。NotebookEdit 是一个已识别但尚未实现的名称，因此启用它会导致启动错误，而不是让 worker 得到一个无法使用的工具。Read 为必选项。

.git、.hg 和 .svn 的内部文件永远无法通过文件系统工具读取或写入；请改用 Run 执行只读 git 命令。

预算限制

所有限制均按每次委派强制执行，并由 deepseek_health 上报，以便 Claude 在发送委派前评估其规模。

超出预算会以 status: "budget_exceeded" 及原因说明结束委派，并且先前已完成的工作会先被上报。

提供商

超时、连接失败、429 和 5xx 会被重试。4xx 会立即暴露，因为重试错误的密钥或错误的请求只会浪费时间。重定向会被直接拒绝，因此 Authorization 头无法被重放到其他主机。

命令策略

Run 以 shell=False 方式执行 argv 数组。可执行文件必须在允许列表中，危险子命令会在结构上被拒绝。可使用配置文件中的 commands.extra_allowed_executables 添加项目专属工具，用 extra_denied_executables 移除某个工具。额外的允许条目无法重新启用被硬性拒绝的程序。

默认拒绝：权限提升、软件包安装、发布、网络工具、shell 及内联代码解释器、破坏性文件系统操作、就地编辑器，以及修改状态或涉及远程的 git 子命令。只读 git（status、diff、log、show、ls-files、rev-parse、blame 等）是允许的。

通用文件读取工具如 cat、head 和 grep 被有意不列入允许列表：它们会以一条命令绕过 Read、Glob 和 Grep 强制执行的秘密路径拒绝列表。只有在你接受这一点的前提下，才可通过 extra_allowed_executables 将其加回。

日志

委派日志仅包含元数据：事件名称、状态、模式、轮次及工具调用次数、token 数量、持续时间和文件数量。不包含任务文本、文件内容、命令输出或提示词正文。日志输出到 stderr，绝不输出到 stdout——stdout 仅承载 MCP 协议流量。API 密钥会从每条记录中擦除，作为最后一道防线。

安全态势

在决定让 worker 指向什么之前，请先阅读本节。

代码中强制执行的内容：

• 每个路径都相对于一个工作区根目录解析。符号链接会首先被解析，之后才对解析结果进行校验，因此指向工作区之外的链接会被拒绝。写入目标会在写入前立即重新校验其父目录。

• 显式配置的工作区若缺失或不可用，将导致启动错误。它绝不会静默回退到更宽泛的目录。

• 包含秘密信息的路径（.env、.env.*、*.pem、*.key、id_rsa、.netrc、.ssh/、.aws/ 及类似路径）以及 .git/.hg/.svn 内部文件对所有工具均被拒绝，并且会从搜索结果中省略，而不仅仅是不可读。

• 委派的 scope 用于限制写入。读取在整个工作区内保持开放，因为 worker 必须进行探索才能完成工作。

• Run 使用 shell=False。由于没有 shell，&&、|、$(...) 和 > 只会作为字面参数文本到达，无法串联第二条命令。可执行文件必须在允许列表中；危险子命令会在 argv 层面被结构性拒绝；绝对路径参数必须位于工作区内；指向已存在被拒绝路径的参数也会被拒绝。

• 软件包安装、发布、网络工具、权限提升以及修改状态或涉及远程的 git 子命令默认被拒绝。通用文件读取工具如 cat 和 grep 同样被拒绝，否则它们会以一条命令绕过秘密路径拒绝列表。

• 子进程会收到一个已剥离凭据的环境，因此 worker 自身的 API 密钥不会出现在命令输出或日志中。

• 写入是原子操作（临时文件、fsync、重命名），因此被中断的写入会保留原始文件不变。Edit 可以要求提供 Read 返回的 SHA-256 值，因此过期的编辑会被拒绝而不是被应用。

• 系统提示词明确指出仓库内容是数据而非指令——并且上述限制在服务端强制执行，因此即使某个文件指示 worker 忽略其指令，也无法赋予它任何权限。

• 日志默认仅包含元数据：事件、状态、计数、持续时间。不包含任务文本、文件内容、命令输出或提示词正文。API 密钥会从每条记录中擦除，作为最后一道防线。

这不是什么：操作系统级别的对抗性沙箱。

这是应用层策略。它限定了困惑、出错或受提示注入影响的 worker 所能采取行动的类别。它不是针对意志坚定的攻击者的遏制边界，这两者并不等同。

具体而言：

• 被允许的测试运行器会执行你项目的代码。pytest 会导入仓库；make test 会运行 Makefile 中规定的任何内容。凡是能通过这种方式触及的内容都是可达的，包括路径策略本会拒绝的文件。

• 没有进程、文件系统或网络隔离——没有容器，没有 bubblewrap 或 seccomp，没有 macOS 沙箱配置文件，没有 Windows 作业对象，没有网络命名空间。被允许的命令会以与服务器进程相同的权限运行。

• 拒绝列表是结构性的而非穷尽性的。这正是可执行文件策略采用允许列表的原因：未知程序会被拒绝，而不会被假定为安全。

不要将其指向你不会从中运行测试的仓库，也不要将其视为审查 diff 的替代品。

已知限制

• NotebookEdit 是一个已识别的工具名称，但没有实现。启用它是一个启动错误， 而不是一个提供给 worker 但无法使用的工具。

• commands.allow_unsafe_shell 会被校验，但不会产生任何效果；这里没有原始的 shell 执行能力。

• worker 无法删除文件。没有 delete 工具，rm 也会被拒绝。

• 没有操作系统级沙箱，如上所述。

• 上下文估算是一种字符启发式方法，会按 provider 报告的用量向上校准。 它是刻意保守的，而非精确的。

• 搜索行为在 ripgrep 和纯 Python 引擎之间略有不同， 因为正则表达式方言不同。每一条结果中都会标明所使用的引擎。

• Windows 受支持并在 CI 中经过测试，但在超时时的进程组终止 相比 POSIX 只是尽力而为。

• 每次调用只有一次委托。没有后台任务，没有持久化的 worker 内存，也没有自动的 git commit 或 push。

开发

uv venv && uv pip install -e ".[dev]"
python -m pytest          # the full suite; no API key and no network needed
python -m ruff check .
python -m ruff format --check .
python -m mypy

测试套件从不调用付费 API：由一个脚本化的假 provider 代替，而 MCP 集成测试则通过 stdio 驱动真实的服务器子进程，针对临时 git 仓库运行。

phases/ 保存了构建此服务器时所用的实现顺序，供参考使用。

GLOBAL_CLAUDE.md 不属于此代码库。它是一个用户级的 Claude Code 指令文件，描述何时进行委托——请将其复制到 ~/.claude/CLAUDE.md， 或并入你已有的同名文件。

许可证

MIT。