deepseek-mcp

Claude Code がリポジトリ作業の1つの境界付きユニットを、ローカルサブエージェントとしてDeepSeekに委任できるようにするMCPサーバー。

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+ と DeepSeek API キーが必要です。ランタイム依存関係は1つ: 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を実行して新しいシェルを開いてください。

引数なしのdeepseek-mcpは、stdio上でMCPサーバーを起動します。それがClaude Codeが実行するものです。通常、自分で直接呼び出すことはありません。

Related MCP server: claude-code

2. APIキーの設定

https://platform.deepseek.com/ からキーを取得します。プロジェクトリポジトリに絶対に置かないでください。 シェルプロファイルからエクスポートします:

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" を出力します。キー自体がレポートに表示されることはありません。

優先順位順の3つのサポートされるキーソース:

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

そうでない場合 — たとえば、シェルプロファイルを読み取らないデスクトップ起動など — 明示的に渡します:

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 が2つのツールとともに表示されるはずです;

• Claudeに deepseek_health を呼び出すよう依頼します。正常に動作するサーバーは、status: "ok"、mode: "enabled"、デフォルトの model と allowed_models 許可リスト、解決されたワークスペースルート、有効な機能、予算制限、およびこのサーバープロセスのワーカーの実行合計を含む usage オブジェクトで応答します。

キーが設定されていなくても、サーバーは起動し、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 でファイルに送信します。

ツールサーフェス

意図的に2つのツール。

deepseek_health

設定とヘルス: ステータス、デフォルトの model と allowed_models 許可リスト、認可されたワークスペースルートとその解決方法、有効な機能、予算制限、およびこのサーバープロセスのワーカーの実行合計を含む usage オブジェクト。シークレットはありません。ワーカーが使用可能であることを確認し、委任を送信する前にそのサイズを見積もるために使用します。

delegate_to_deepseek

散文のブロブではなく構造化された契約としての、1つの境界付き作業ユニット:

{
  "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 は委任がそれを要求した場合にのみ存在し、5つのリポジトリマップフィールドを保持します。debug_ledger は、サーバーが debug 有効で実行されている場合にのみ入力される、ツール呼び出しごとに1行のコンパクトな実行台帳です。metrics はこの委任自身のトークン使用量と形状を報告します。session_usage はこのサーバープロセスのワーカーの実行合計を保持し、この委任を含みます — delegations、turns、tool_calls、prompt_tokens、completion_tokens、total_tokens、since（常にリテラル "server start"）。

{"type": "text"}usage と session_usage の背後にあるカウンターはインメモリで、サーバープロセスにスコープされています。MCP サーバーが再起動するとリセットされ、それがまさに since フィールドが記録する内容です。ディスクには永続化されません。ワーカーに到達した委任のみがカウントされます。早期に拒否されたリクエスト（サーバー無効、リクエストフィールド不正、allowed_models 許可リスト外のモデル）はモデルを呼び出していないため、delegations やトークン数は増加しません。total_tokens は保存されるのではなく構成要素から計算されるため、ずれることはありません。

ステータス: completed、partial、blocked、failed、budget_exceeded、disabled。想定される失敗（設定不良、拒否されたパス、拒否されたコマンド、予算超過、プロバイダーエラー）はすべて、理由を伴うこれらのいずれかとして返されます。Python のトレースバックが返されることはありません。

結果は結論を伝え、生の Read/Grep/ツールのトランスクリプトは伝えません。デバッグ台帳はコンパクトな台帳（ツール呼び出しごとに1行）であり、デバッグが有効な場合でもツール出力ではありません。

モードは狭めるだけで、広げることはない

モードはサーバーの設定済み機能と交差します。サーバーが許可する以上のものを要求するリクエストは、API 呼び出しの前に拒否されます。ポリシーを広げることはできません。

ワーカーが信頼されないもの

結果のうち2つはモデルから来るものではありません。

• 変更ファイルリスト は、ツールの監視と、実行前に取得したスナップショットとの 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トークン）。

コンテキストは増え続けるトランスクリプトではなく、予算化されたリソースとして扱われます。しきい値を超えると、古いツールペイロードは決定的な実行台帳からの1行エントリに置き換えられます。それでも不十分な場合は、台帳が何をしたかを記録しているため、古いターン全体が削除されます。システムプロンプト、元のタスク契約、最近のターン、台帳は常に保持されます。要約に余分なモデル呼び出しが費やされることはなく、ワーカーが追い出された詳細を必要とする場合はファイルを再度読み取ります。

すべての制限は設定可能で、deepseek_health によって報告されます。

設定リファレンス

予約済み とマークされた設定は起動時に検証されますが、まだ消費されません。

優先順位

環境変数 > ユーザー設定ファイル > 組み込みデフォルト

モデル選択にはもう1つ上のレベルがあります。単一の委任が独自のモデルを指定できるため、完全な順序は

タスクごとのモデル > 環境変数 > ユーザー設定ファイル > 組み込みデフォルト

タスクごとのモデルは delegate_to_deepseek の model パラメータです。サーバーの allowed_models が空でない場合、それは許可リストであり、それ以外を指定するリクエストは API 呼び出しの前に blocked として拒否されます。モデルの選択は、委任モードがサーバーの機能に狭められるのとまったく同じように、オペレーターが許可したものに狭められます。

欠落、不正、または矛盾した設定はエラーです。サーバーはより広いワークスペースやより寛容なポリシーにフォールバックしません。

設定の読み込みに失敗した場合、プロセスはまだ起動し、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 がその外にある場合、API 呼び出しの前に blocked として拒否されます。空の場合は、整形式のモデル名が受け入れられます。

資格情報とエンドポイント

API キーがないと作業はできません。起動時にサーバーが無効として報告されます。

ワークスペース

明示的なワークスペースがない場合、ルートはプロセスの作業ディレクトリから .git、.hg、.svn、pyproject.toml、package.json、go.mod、Cargo.toml を探して上方向に移動して検出されます。見つからない場合は、作業ディレクトリ自体が使用され、警告が記録されます。

明示的なワークスペースが存在しない、読み取れない、ディレクトリでない、相対パスである、またはファイルシステムのルートである場合、起動エラーになります。作業ディレクトリに縮退することはありません。サーバーはプロジェクト内に存在する必要はなく、プロジェクトを変更して自分自身をアクティブ化することはありません。

ツール

デフォルトで有効なツールは NotebookEdit 以外のすべてです。NotebookEdit は認識された名前ですが、実装はまだありません。そのため、有効にすると、ワーカーに提供されて使用できないツールではなく、起動エラーになります。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 を使用してツールを削除します。追加の許可エントリでも、ハード拒否されたプログラムを再び有効にすることはできません。

デフォルトで拒否されるもの: 権限昇格、パッケージのインストール、公開、ネットワークユーティリティ、シェルおよびインラインコードインタープリタ、破壊的なファイルシステム操作、インプレースエディタ、および変更を伴うまたはリモートの 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 キーはすべてのレコードから最後の防御として除去されます。

セキュリティ体制

ワーカーをどこに向けるかを決める前に、このセクションをお読みください。

ここで説明する保護は、モデル選択や分析機能によって変わることはありません: 境界付きコンテキストによる圧縮、ワークスペースサンドボックス、コマンド許可リスト、コミットやプッシュなし、デフォルトでのパッケージインストールやネットワークアクセスなし、そしてトークンとツールのメトリクスを運ぶ構造化された結果。

コードで強制されること:

• すべてのパスは単一のワークスペースルートに対して解決されます。シンボリックリンクは最初に解決され、その結果が検証されるため、ツリーの外へのリンクは拒否されます。書き込みターゲットは、書き込みの直前に親ディレクトリが再検証されます。

• 明示的に設定されたワークスペースが存在しない、または使用できない場合は、起動エラーになります。より広いディレクトリに暗黙的にフォールバックすることはありません。

• シークレットを含むパス(.env、.env.*、*.pem、*.key、id_rsa、.netrc、.ssh/、.aws/ など)および .git/.hg/.svn の内部は、すべてのツールに対して拒否され、単に読み取れないだけでなく、検索結果からも除外されます。

• デリゲーションの scope は書き込みを制限します。読み取りはワークスペース全体に対して開かれたままです。なぜなら、ワーカーは仕事をするために探索する必要があるからです。

• Run は shell=False を使用します。シェルは存在しないため、&&、|、$(...)、> はリテラルの引数テキストとして届き、2番目のコマンドを連結することはできません。実行可能ファイルは許可リストに登録されている必要があり、危険なサブコマンドは argv 上で構造的に拒否され、絶対パス引数はワークスペース内に収まる必要があり、既存の拒否パスを指定する引数は拒否されます。

• パッケージのインストール、公開、ネットワークユーティリティ、権限昇格、および変更を伴うまたはリモートの git サブコマンドは、デフォルトで拒否されます。cat や grep などの汎用ファイルリーダーも同様に拒否されます。これらはシークレットパス拒否リストを単一コマンドで迂回できてしまうからです。

• サブプロセスは資格情報が除去された環境を受け取るため、ワーカーの API キーがコマンド出力やログに現れることはありません。

• 書き込みはアトミックです(temp ファイル、fsync、rename)。そのため、書き込みが中断されても元のファイルは無傷のままです。Edit は Read が返した SHA を要求できるため、古い編集は拒否されます。

• システムプロンプトは、リポジトリのコンテンツはデータであり命令ではないと明示しています — そして上記の制限はサーバー側で強制されるため、ワーカーに指示を無視させようとするファイルは、何も許可を与えることはできません。

• ログはデフォルトでメタデータのみです: イベント、ステータス、回数、所要時間。タスクテキスト、ファイル内容、コマンド出力、プロンプト本文は記録されません。API キーはすべてのレコードから最後の防御として除去されます。

これは OS レベルの敵対的サンドボックスではありません。

これはアプリケーションレベルのポリシーです。混乱した、誤った、またはプロンプトインジェクションを受けたワーカーが取れるアクションのカテゴリを制限します。決意のある攻撃者に対する封じ込め境界ではありません。この2つは同等ではありません。

具体的には:

• 許可されたテストランナーは、あなたのプロジェクトのコードを実行します。pytest はリポジトリをインポートし、make test は Makefile が指定するものを実行します。その方法で到達可能なものはすべて到達可能であり、パスポリシーが拒否したファイルも含まれます。

• プロセス、ファイルシステム、ネットワークの分離はありません — コンテナも、bubblewrap や seccomp も、macOS サンドボックスプロファイルも、Windows ジョブオブジェクトも、ネットワーク名前空間もありません。許可されたコマンドは、サーバープロセスと同じ権限で実行されます。

• 拒否リストは網羅的ではなく構造的です。これが、実行可能ファイルポリシーが許可リストである理由です: 未知のプログラムは安全と見なされるのではなく拒否されます。

テストを実行しないようなリポジトリにこれを向けないでください。また、これを diff のレビューの代わりとして扱わないでください。

既知の制限事項

• NotebookEdit は認識されているツール名ですが、実装はありません。有効にすると、ワーカーに提供されるツールではなく、起動エラーになります。

• commands.allow_unsafe_shell は検証されますが、何も行いません。生のシェル実行はありません。

• ワーカーはファイルを削除できません。削除ツールはなく、rm は拒否されます。

• OS レベルのサンドボックスはありません(上記のとおり)。

• コンテキスト見積もりは文字ヒューリスティックであり、プロバイダーの報告する使用量に合わせて上方調整されます。意図的に控えめであり、正確ではありません。

• 検索動作は ripgrep エンジンと純 Python エンジンでわずかに異なります。なぜなら、正規表現の方言が異なるからです。使用されたエンジンはすべての結果で明示されます。

• Windows はサポートされ、CI でテストされていますが、タイムアウト時のプロセスグループ終了は POSIX と比較してベストエフォートです。

• 呼び出しごとにデリゲーションは1つだけです。バックグラウンドジョブ、永続的なワーカーメモリ、自動的な git コミットやプッシュはありません。

開発

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 統合テストは一時的な git リポジトリに対して stdio 経由で実際のサーバーサブプロセスを駆動します。

phases/ には、このサーバーが構築された実装順序が保持されており、参照用に残されています。

GLOBAL_CLAUDE.md はこのコードベースの一部ではありません。これはユーザーレベルの Claude Code 命令ファイルで、いつデリゲーションするかを説明しています — ~/.claude/CLAUDE.md にコピーするか、既存のファイルにマージしてください。

ライセンス

MIT。