deepseek-mcp

MCP-сервер, который позволяет Claude Code делегировать DeepSeek одну ограниченную единицу работы с репозиторием как локальному субагенту.

Claude остается оркестратором: он определяет масштаб, архитектуру и корректность. DeepSeek — исполнитель для части, требовательной к токенам: исследование репозитория, внесение рутинных или повторяющихся изменений и запуск тестов — в пределах одного авторизованного рабочего пространства и при жестких бюджетах.

Смысл в том, чтобы не платить дважды за один и тот же контекст. Если Claude читает подсистему, а затем DeepSeek читает ее снова, ничего не сэкономлено; поэтому решение о делегировании принимается до широкого чтения.

User
 ↓
Claude: plan + define goal/scope
 ↓
DeepSeek: inspect repo + read code + implement + test
 ↓
DeepSeek: compact structured summary
 ↓
Claude: review diff/results + final answer

DeepSeek — основной работник по репозиторию; Claude — оркестратор. Claude планирует, принимает архитектурные решения и решения по безопасности, проверяет возвращенный diff и пишет окончательный ответ. DeepSeek выполняет работу по репозиторию: исследование, Glob/Grep/ Read, понимание кода, реализацию, тестирование и рутинные исправления. Claude делегирует до широкого чтения исходных файлов, а DeepSeek сам находит соответствующие файлы в пределах авторизованной области и возвращает компактную структурированную сводку — Claude никогда не отправляет содержимое файлов.

Требуется Python 3.11+ и API-ключ DeepSeek. Одна зависимость времени выполнения: 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 без аргументов запускает MCP-сервер на stdio. Именно это запускает Claude Code; обычно вам не нужно вызывать его самостоятельно.

Related MCP server: Hydra

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", моделью по умолчанию model и списком разрешенных моделей allowed_models, разрешенным корнем рабочего пространства, включенными возможностями, лимитами бюджета и объектом usage с текущими итогами работника для этого процесса сервера.

Без настроенного ключа сервер все равно запускается и отвечает на deepseek_health — сообщая status: "error", mode: "disabled" — так что проблему можно диагностировать изнутри Claude Code. В этом состоянии он не выполняет никакой работы.

5. Устранение неполадок

Журналы идут в stderr как записи event key=value, никогда в stdout. Повысьте детализацию с помощью DEEPSEEK_MCP_LOG_LEVEL=DEBUG или отправьте их в файл с DEEPSEEK_MCP_LOG_FILE=/absolute/path.log.

Поверхность инструментов

Два инструмента, намеренно.

deepseek_health

Конфигурация и состояние: статус, модель по умолчанию model и список разрешенных моделей allowed_models, авторизованный корень рабочего пространства и способ его определения, включенные возможности, лимиты бюджета и объект usage с текущими итогами работника для этого процесса сервера. Без секретов. Используйте его, чтобы подтвердить, что работник доступен, и чтобы оценить масштаб делегирования перед его отправкой.

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, read, edit, run, repair — и возвращает компактный результат, никогда не транскрипт:

{
  "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
  },
  "session_usage": {
    "delegations": 3, "turns": 19, "tool_calls": 31,
    "prompt_tokens": 51200, "completion_tokens": 6400,
    "total_tokens": 57600, "since": "server start"
  },
  "model": "deepseek-chat",
  "analysis": {
    "important_files": ["src/importer/validate.py"],
    "architecture_notes": ["validate_row is the single entry point for row checks."],
    "dependencies": ["src/importer/schema.py"],
    "suggested_scope": ["src/importer/**", "tests/importer/**"],
    "risks": ["Changing the None handling may affect callers that rely on the old behaviour."]
  },
  "debug_ledger": ["R src/importer/validate.py", "E src/importer/validate.py", "X pytest tests/importer -q"]
}

model — это модель, которая фактически выполнила делегирование, после разрешения переопределения для конкретной задачи. analysis присутствует только тогда, когда делегирование запрашивало его, и содержит пять полей карты репозитория. debug_ledger — это компактный журнал выполнения по одной строке на вызов инструмента, заполняемый только когда сервер работает с включенным debug. metrics сообщает об использовании токенов и форме этого делегирования; session_usage содержит текущие итоги работника для этого процесса сервера, включая это делегирование — delegations, turns, tool_calls, prompt_tokens, completion_tokens, total_tokens и since (всегда буквально "server start").

Счётчик за usage и session_usage хранится в памяти и ограничен процессом сервера: он сбрасывается при перезапуске MCP-сервера, что как раз и фиксирует поле since. На диск он не сохраняется. Учитываются только те делегирования, которые дошли до воркера: запрос, отклонённый раньше (сервер отключён, недопустимое поле запроса или модель вне списка разрешённых allowed_models), никогда не вызывал модель, поэтому не увеличивает delegations и не влияет на счётчики токенов. total_tokens вычисляется из своих частей, а не хранится, поэтому не может «уплыть».

Статусы: completed, partial, blocked, failed, budget_exceeded, disabled. Ожидаемые сбои — плохая конфигурация, отклонённый путь, запрещённая команда, исчерпанный бюджет, ошибка провайдера — все возвращаются в виде одного из этих статусов с указанием причины. Трейсбек Python — никогда.

Результаты содержат выводы, а не сырые транскрипты Read/Grep/инструментов. Отладочный журнал — это компактный журнал: одна строка на вызов инструмента, а не вывод инструмента, даже когда отладка включена.

Режимы сужают, но никогда не расширяют

Режим пересекается с настроенными возможностями сервера. Запрос, требующий больше, чем предоставляет сервер, отклоняется до любого вызова 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 токенов).

Контекст рассматривается как бюджетный ресурс, а не растущий транскрипт. Выше порога старые полезные данные инструментов заменяются однострочными записями из детерминированного журнала выполнения; если этого недостаточно, отбрасываются целые старые ходы, поскольку журнал всё равно фиксирует, что они делали. Системный промпт, исходный контракт задачи, недавние ходы и журнал всегда сохраняются. Никогда не тратится дополнительный вызов модели на суммаризацию, и если воркеру нужна вытесненная деталь, он читает файл заново.

Все лимиты настраиваются и сообщаются через deepseek_health.

Справочник по конфигурации

Настройки, помеченные как зарезервированные, проверяются при запуске, но пока не используются.

Приоритет

переменная окружения > файл конфигурации пользователя > встроенное значение по умолчанию

Выбор модели имеет ещё один уровень выше: отдельное делегирование может указывать свою собственную модель, поэтому полный порядок такой:

модель задачи > переменная окружения > файл конфигурации пользователя > встроенное значение по умолчанию

Модель задачи — это параметр model в delegate_to_deepseek. Когда allowed_models сервера не пуст, это список разрешённых, и запрос с любым другим именем отклоняется как blocked до любого вызова API — выбор модели сужается до того, что разрешил оператор, точно так же, как режимы делегирования сужаются до возможностей сервера.

Отсутствующая, некорректная или противоречивая настройка — это ошибка. Сервер не откатывается к более широкому рабочему пространству или более мягкой политике.

Если конфигурация не загружается, процесс всё равно запускается и всё равно отвечает на deepseek_health, но сообщает status: "error", mode: "disabled" и не выполняет никакой работы. Запустите deepseek-mcp --check, чтобы увидеть тот же отчёт в командной строке.

Расположение файла конфигурации

Файл конфигурации пользователя находится вне любого проекта:

DEEPSEEK_MCP_CONFIG переопределяет путь. Если он задан, а файл не существует, запуск завершается ошибкой, а не молча использует значения по умолчанию. Отсутствие файла конфигурации в месте по умолчанию — нормально; пустой файл — нормально; неизвестные ключи — ошибка.

Схема файла конфигурации

Каждый ключ необязателен.

{
  "model": "deepseek-chat",
  "allowed_models": ["deepseek-chat", "deepseek-reasoner"],
  "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, который указывает имя переменной окружения для чтения.

allowed_models — необязательный список разрешённых имён моделей, которые может запросить делегирование. Если он не пуст, настроенная model должна быть в нём (иначе настройки противоречат друг другу), а запрос с model вне списка отклоняется как blocked до любого вызова API. Пустое значение означает, что принимается любое корректно сформированное имя модели.

Учётные данные и конечная точка

Нет API-ключа — нет работы: при запуске сервер сообщается как отключённый.

Рабочее пространство

Без явного рабочего пространства корень определяется подъёмом вверх от рабочего каталога процесса в поисках .git, .hg, .svn, pyproject.toml, package.json, go.mod или Cargo.toml. Если ничего не найдено, используется сам рабочий каталог, и записывается предупреждение.

Явное рабочее пространство, которое отсутствует, нечитаемо, не является каталогом, относительно или является корнем файловой системы, — это ошибка запуска. Оно никогда не деградирует до рабочего каталога. Серверу не обязательно находиться внутри вашего проекта, и он никогда не изменяет проект для своей активации.

Инструменты

Инструменты, включённые по умолчанию, — все, кроме NotebookEdit. NotebookEdit — это распознанное имя без реализации, поэтому его включение — ошибка запуска, а не инструмент, который воркеру предлагают и который он не может использовать. Read обязателен.

Внутренности .git, .hg и .svn никогда не читаются и не записываются через файловые инструменты; используйте вместо этого команду git только для чтения через Run.

Бюджетные лимиты

Все применяются к каждому делегированию и сообщаются через deepseek_health, чтобы Claude мог оценить делегирование перед отправкой.

Превышение бюджета завершает делегирование со status: "budget_exceeded" и причиной, после сообщения о уже выполненной работе.

Провайдер

Таймауты, ошибки подключения, 429 и 5xx повторяются. Ошибка 4xx проявляется немедленно, потому что повторять плохой ключ или плохой запрос — только тратить время. Редиректы отклоняются полностью, чтобы заголовок Authorization не мог быть воспроизведен на другом хосте.

Политика команд

Run выполняет массив argv с shell=False. Исполняемый файл должен быть в списке разрешённых, а опасные подкоманды отклоняются структурно. Используйте в конфигурационном файле commands.extra_allowed_executables, чтобы добавить специфический для проекта инструмент, и extra_denied_executables, чтобы удалить его. Дополнительная запись разрешения не может повторно включить программу, находящуюся в жёстком запрете.

По умолчанию отклоняются: повышение привилегий, установка пакетов, публикация, сетевые утилиты, оболочки и интерпретаторы встроенного кода, разрушительные операции с файловой системой, редакторы на месте, а также изменяющие или удалённые подкоманды git. Только для чтения git (status, diff, log, show, ls-files, rev-parse, blame, …) — разрешено.

Универсальные чтение файлов, такие как cat, head и grep, намеренно не в списке разрешённых: они были бы обходом в одну команду списка запрещённых секретных путей, который обеспечивают Read, Glob и Grep. Добавьте его обратно через extra_allowed_executables, только если вы с этим согласны.

Ведение журнала

Журналирование делегирования — только метаданные: имя события, статус, режим, количество вызовов инструментов и ходов, количество токенов, длительность и количество файлов. Никакого текста задачи, содержимого файлов, вывода команд или тел подсказок. Журналы идут в stderr, никогда в stdout — stdout несёт только трафик протокола MCP. Ключ API удаляется из каждой записи как запасной вариант.

Позиция безопасности

Прочитайте этот раздел, прежде чем решать, на что направить рабочий процесс.

Описанные здесь защиты не изменяются функциями выбора модели и анализа: ограниченный контекст с компактизацией, песочница рабочей области, список разрешённых команд, без коммитов или push, без установки пакетов или сетевого доступа по умолчанию, и структурированный результат, содержащий метрики токенов и инструментов.

Что применяется в коде:

• Каждый путь разрешается относительно одного корня рабочей области. Символические ссылки проверяются сначала, и результат — это то, что проверяется, поэтому ссылка за пределы дерева отклоняется. Для целей записи родительский каталог повторно проверяется непосредственно перед записью.

• Явно настроенная рабочая область, которая отсутствует или непригодна, — это ошибка запуска. Она никогда не опускается до более широкого каталога.

• Пути с секретами (.env, .env.*, *.pem, *.key, id_rsa, .netrc, .ssh/, .aws/ и подобные) и внутренности .git/.hg/.svn запрещены для каждого инструмента и исключены из результатов поиска, а не просто нечитаемы.

• Область делегирования scope ограничивает записи. Чтения остаются открытыми во всей рабочей области, потому что рабочему процессу нужно исследовать, чтобы выполнять свою работу.

• Run использует shell=False. Оболочки нет, поэтому &&, |, $(...) и > приходят как буквальный текст аргумента и не могут объединить вторую команду. Исполняемый файл должен быть в списке разрешённых, опасные подкоманды отклоняются структурно через argv, аргументы абсолютных путей должны находиться внутри рабочей области, а аргумент, указывающий на существующий запрещённый путь, отклоняется.

• Установка пакетов, публикация, сетевые утилиты, повышение привилегий и изменяющие или удалённые подкоманды git отклоняются по умолчанию. Также универсальные чтение файлов, такие как cat и grep, которые в противном случае были бы обходом в одну команду списка запрещённых секретных путей.

• Дочерние процессы получают окружение с удалёнными учётными данными, так что собственный ключ API рабочего процесса не может появиться в выводе команды или журнале.

• Записи атомарны (временный файл, fsync, переименование), поэтому прерванная запись оставляет исходный файл нетронутым. Edit может требовать SHA-256, который вернул Read, поэтому устаревшее редактирование отклоняется, а не применяется.

• Системная подсказка утверждает, что содержимое репозитория — это данные, а не инструкция — и перечисленные выше ограничения применяются на стороне сервера, поэтому файл, который говорит рабочему процессу игнорировать его инструкции, не может дать ему ничего.

• Журналы по умолчанию содержат только метаданные: событие, статус, счётчики, длительность. Никакого текста задачи, содержимого файлов, вывода команд или тел подсказок. Ключ API удаляется из каждой записи как запасной вариант.

Что это не: песочница на уровне ОС против злонамеренного окружения.

Это политика уровня приложения. Она ограничивает категорию действий, которые может совершить запутанный, ошибочный или инъекционно-подсказанный рабочий процесс. Это не граница изоляции против решительного противника, и эти два понятия не эквивалентны.

Конкретно:

• Разрешённый тестовый раннер выполняет код вашего проекта. pytest импортирует репозиторий; make test запускает то, что говорит Makefile. Всё, что достижимо этим способом, достижимо, включая файлы, которые политика путей отказала бы.

• Нет изоляции процессов, файловой системы или сети — никакого контейнера, bubblewrap или seccomp, профиля песочницы macOS, объекта задания Windows, сетевого пространства имён. Команда, которая разрешена, выполняется с теми же привилегиями, что и процесс сервера.

• Списки запретов структурны, а не исчерпывающие. Это причина, по которой политика исполняемых файлов является списком разрешённых: неизвестные программы отклоняются, а не считаются безопасными.

Не направляйте это на репозиторий, из которого вы не стали бы запускать тесты, и не рассматривайте это как замену просмотру diff.

Известные ограничения

• NotebookEdit — это распознаваемое имя инструмента без реализации. Включение его приводит к ошибке запуска, а не к инструменту, который предлагается рабочему процессу и не может использоваться.

• commands.allow_unsafe_shell проверяется, но ничего не делает; нет выполнения без оболочки.

• Рабочий процесс не может удалять файлы. Инструмента удаления нет, и rm отклоняется.

• Нет песочницы на уровне ОС, как указано выше.

• Оценка контекста — это эвристика на основе символов, откалиброванная вверх по сообщённому использованию от провайдера. Она намеренно консервативна, а не точная.

• Поведение поиска немного отличается между движками ripgrep и чисто-Python, потому что диалекты регулярных выражений различаются. Используемый движок указывается в каждом результате.

• Windows поддерживается и тестируется в CI, но завершение группы процессов по таймауту там выполняется по принципу "лучшее усилие" по сравнению с POSIX.

• Одно делегирование за раз. Нет фоновых задач, постоянной памяти рабочего процесса и автоматического 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: вместо него используется скриптованный фейковый провайдер, а интеграционные тесты MCP запускают реальный подпроцесс сервера через stdio против временных git-репозиториев.

phases/ содержит последовательность реализации, из которой построен этот сервер, для справки.

GLOBAL_CLAUDE.md не является частью этого кодового базиса. Это файл инструкций Claude Code на уровне пользователя, описывающий, когда делегировать — скопируйте его в ~/.claude/CLAUDE.md, или объедините с тем, который у вас уже есть.

Лицензия

MIT.