Claude Code MCP Server

Claude Code MCP サーバー

AI ツールが Claude Code とプログラムからやり取りできるようにする MCP（Model Context Protocol）サーバーです。会話の継続性と非同期実行をサポートし、強力なエージェント間ワークフローを実現します。

概要

この MCP サーバーは、AI ツールと Claude Code の橋渡しをします。他の AI システムが Claude Code 経由でプロンプトを実行し、会話の継続性を保てるよう、セッション状態を維持します。同期実行と非同期実行の両方に対応しているため、簡単なクエリから長時間かかる処理まで幅広く利用できます。

特長

• 新しい会話 - 新しい会話を開始するための start ツール（同期／非同期）
• 会話の再開 - 既存の会話を継続するための resume ツール（同期／非同期）
• 作業ディレクトリのサポート - 任意のディレクトリで Claude Code を実行（新しい会話のみ）
• タスク管理 - 経過時間を確認しながらタスクを監視し、処理をキャンセルして結果を取得
• 会話の分岐 - 過去の任意の応答 ID から会話を再開して分岐
• 堅牢な CLI 検出 - Claude Code のインストール先を自動検出
• 権限のバイパス - --dangerously-skip-permissions を使用してすべての機能を利用
• 環境設定 - 環境変数でカスタマイズ可能
• デバッグログ - トラブルシューティング用の詳細ログ（任意）
• モジュール型アーキテクチャ - 関心事を分離した、整理され保守しやすいコードベース
• 自動公開 - リリース用の GitHub Actions ワークフロー
• システム通知 - タスクの開始時と完了時に、異なるサウンド付きの macOS 通知を表示
• プロセスのクリーンアップ - MCP サーバー切断時に孤立したプロセスを自動的にクリーンアップ

設計上の決定事項

この MCP サーバーでは、明確さと実用性を重視して意図的に設計上の選択をしています。

応答 ID とセッション ID

「セッション ID」ではなく**「応答 ID」**という用語を使用しています。理由は次のとおりです。

• 会話の各ターンで新しい応答 ID が生成される
• 過去の任意の応答 ID から会話を分岐できる
• 実際には各応答が新しい分岐点となるため、「セッション」という用語は継続的なセッションを誤って示唆する

--continue フラグには非対応

Claude Code の --continue フラグには意図的に対応していません。理由は次のとおりです。

• 複数のエージェントが並行して動作する場合、「直近の会話」が曖昧になる
• 各エージェントは通常、独立したタスクを処理する
• 会話を正確に制御するには、明示的な応答 ID を指定して resume ツールを使用する

権限モード

現在は --permission-mode bypassPermissions と機能的に同等の --dangerously-skip-permissions を使用しています。この非推奨フラグは、将来のバージョンで最新の権限モードシステムに置き換えられ、次のモードが利用可能になります。

• 読み取り専用のコード分析を行う plan モード
• ファイル変更を自動承認しつつ、危険な操作は確認する acceptEdits
• 標準的な対話型プロンプトを使う default
• 現在の動作（すべての権限を許可）を維持する bypassPermissions

前提条件

• Node.js 18+ ランタイム
• Claude Code CLI がインストールされ、設定済みであること
• 利用規約に同意するため、Claude Code を --dangerously-skip-permissions を付けて一度実行する必要があります

インストールとセットアップ

オプション 1：NPX（インストール不要）

npx を使って直接実行します。

{
  "mcpServers": {
    "claude": {
      "command": "npx",
      "args": ["claude-mcp"]
    }
  }
}

オプション 2：ローカル開発

1. クローンしてインストール：

   git clone https://github.com/ebeloded/claude-mcp.git
   cd claude-mcp
   npm install
   

2. MCP 設定で使用：

   {
     "mcpServers": {
       "claude": {
         "command": "node",
         "args": ["/path/to/claude-mcp/server.js"]
       }
     }
   }
   

Claude Code の初回セットアップ

重要： 上記のセットアップを使用する前に、Claude Code を一度実行して権限に同意してください。

claude --dangerously-skip-permissions

プロンプトが表示されたら利用規約に同意してください（初回のみ必要です）。

設定

MCP クライアントの設定

MCP 設定ファイルに設定を追加します。

• Cursor： ~/.cursor/mcp.json
• Windsurf： ~/.codeium/windsurf/mcp_config.json

環境変数

• CLAUDE_CLI_NAME：Claude CLI のバイナリ名を上書きします（デフォルト："claude"）
• MCP_CLAUDE_DEBUG："true" に設定すると、詳細なデバッグログを有効にします
• MCP_NOTIFICATIONS："false" に設定すると、macOS システム通知を無効にします

ツール

start - 新しい会話

Claude Code で新しい会話を開始します。同期待ちと非同期実行の両方に対応しています。

パラメーター：

• message（string、必須）：エージェントに送信するメッセージです。希望する内容を具体的に記述してください。ファイルパス、希望する出力形式、制約事項などを含めてください。
• workingDirectory（string、省略可）：実行に使用する作業ディレクトリです。絶対パス、または現在のディレクトリからの相対パスを指定します。別のプロジェクトや Git ワークツリーで作業する場合に便利です。
• appendSystemPrompt（string、省略可）：デフォルトのシステムプロンプトに追加するテキストです。
• async（boolean、省略可）：非同期で実行するかどうかを指定します。デフォルトは true です。

例（同期）：

// Simple query in current directory
start({
  message: "What's 2 + 2?",
  async: false,
})

// Analyze specific code in project directory
start({
  message:
    "Analyze the authentication logic in src/auth.js and list security vulnerabilities as bullet points",
  workingDirectory: "/path/to/project",
  async: false,
})

レスポンス形式（同期）：

4

Response ID: 938c8c6d-1897-4ce4-a727-d001a628a279

例（非同期）：

start({
  message:
    "Analyze the entire codebase for performance bottlenecks, focusing on database queries and API endpoints. Provide specific recommendations with file locations.",
})

start({
  message:
    "Review all React components in src/components/ for accessibility issues and generate a detailed report with WCAG compliance suggestions",
  workingDirectory: "/path/to/frontend-project",
})

レスポンス（非同期）：

Task started successfully. Use status with task ID: 550e8400-e29b-41d4-a716-446655440000

resume - 会話の続行

Claude Code で既存の会話を続行します。同期待ちと非同期実行の両方に対応しています。元の会話の作業ディレクトリを使用します。

パラメーター：

• message（string、必須）：エージェントに送信するメッセージです。必要に応じて以前のコンテキストを参照してください。エージェントは会話の履歴を記憶しています。
• previousResponseId（string、必須）：以前のエージェントのレスポンスから取得したレスポンス ID です。会話を分岐または続行する際に使用します。
• async（boolean、省略可）：非同期で実行するかどうかを指定します。デフォルトは true です。

例（同期）：

resume({
  message: "What did I just ask you?",
  previousResponseId: "938c8c6d-1897-4ce4-a727-d001a628a279",
  async: false,
})

レスポンス形式（同期）：

You asked me about 2 + 2.

Response ID: b2c3d4e5-f6g7-8901-bcde-f23456789012

例（非同期）：

resume({
  message: "Continue that analysis with more detail",
  previousResponseId: "938c8c6d-1897-4ce4-a727-d001a628a279",
})

レスポンス（非同期）：

Task started successfully. Use status with task ID: 661f9511-e30c-41e5-a927-556677889900

status - タスクの状態監視

非同期タスクの状態と進行状況を確認します。

パラメーター：

• taskId（string、必須）：ask_async が返すタスク ID です。

例：

status({
  taskId: "550e8400-e29b-41d4-a716-446655440000",
})

レスポンス（実行中）：

Task 550e8400-e29b-41d4-a716-446655440000:
Status: running
Elapsed: 45s
Working Directory: /Users/ebeloded/Code/claude-mcp
Created: 2025-05-28T21:15:30.123Z
Updated: 2025-05-28T21:16:15.456Z

レスポンス（完了）：

Task 550e8400-e29b-41d4-a716-446655440000:
Status: completed
Elapsed: 1m 52s
Working Directory: /Users/ebeloded/Code/claude-mcp
Created: 2025-05-28T21:15:30.123Z
Updated: 2025-05-28T21:17:22.789Z

Result: [Claude's comprehensive analysis here...]
Response ID: 938c8c6d-1897-4ce4-a727-d001a628a279
Cost: $0.045
Duration: 112456ms

cancel - タスクのキャンセル

実行中の非同期タスクをキャンセルします。

パラメーター：

• taskId（string、必須）：キャンセルするタスクの ID です。

例：

cancel({
  taskId: "550e8400-e29b-41d4-a716-446655440000",
})

レスポンス：

Task 550e8400-e29b-41d4-a716-446655440000 cancelled successfully

アーキテクチャ

保守性を高めるため、サーバーはモジュール式のアーキテクチャを採用しています。

claude-mcp/
├── server.js                    # Main entry point & orchestration
├── src/
│   ├── server/
│   │   └── setup.js             # MCP server setup and signal handling
│   ├── services/
│   │   ├── TaskService.js       # Async task lifecycle & notification management
│   │   └── ClaudeService.js     # Claude CLI execution logic
│   ├── tools/
│   │   └── (MCP tool definitions)
│   └── utils/
│       ├── errors.js            # Error handling utilities
│       ├── logger.js            # Debug logging utilities
│       └── validation.js       # Input validation utilities
└── tests/
    └── *.e2e.test.ts            # End-to-end tests

コンポーネントの役割

• TaskService：非同期タスクの作成、追跡、進行状況の監視、キャンセル、クリーンアップ、システム通知を処理します。
• ClaudeService：プロセスグループ管理を行いながら、同期・非同期の両方のパターンで Claude CLI の検出と実行を管理します。
• Setup：MCP サーバーの初期化、シグナル処理、正常なシャットダウンの調整を行います。
• Tools：MCP SDK のパターンに従い、6 つの MCP ツールを server.js に直接登録します。
• Server：コンポーネントを連携させる、最小限のオーケストレーションレイヤーです。

開発

テスト

npm test

テストスイートには次の項目が含まれています。

• セッション管理を伴う同期実行
• 非同期タスクの作成と状態監視
• タスクのキャンセル機能
• エッジケースのエラー処理

デバッグモード

MCP_CLAUDE_DEBUG=true を設定すると、詳細なログを有効にできます。

{
  "mcpServers": {
    "claude": {
      "command": "node",
      "args": ["/path/to/claude-mcp/server.js"],
      "env": {
        "MCP_CLAUDE_DEBUG": "true"
      }
    }
  }
}

ローカル開発

# Install dependencies
npm install

# Run tests
npm test

# Start in debug mode
MCP_CLAUDE_DEBUG=true npm start

STDIO ロギング（重要）

このサーバーは STDIO 経由で通信します。標準出力に通常のログを書き込まないでください。JSON-RPC が破損します。すべてのログは logger ユーティリティ経由で標準エラー出力に書き込まれます。ロギングについては、MCP のクイックスタートガイドを参照してください：https://modelcontextprotocol.io/quickstart/server.md

ユースケース

新しい会話（start）

• 新しい会話や分析の開始
• 別のコードベースでの作業（workingDirectory を使用）
• 簡単な問い合わせと即時応答（同期モード）
• ノンブロッキングで実行する必要がある長時間処理（非同期モード）
• 別のディレクトリや Git ワークツリーにあるプロジェクトの分析
• 特定の動作に合わせたカスタムシステムプロンプト

会話の再開（resume）

• 既存の会話とコンテキストを引き継ぎます
• 以前の回答や分析を基に作業します
• 過去のコンテキストについて質問します
• 任意の過去の回答から会話を分岐します
• 同じ作業ディレクトリ内で会話の継続性を維持します
• 同期モードと非同期モードの両方で実行できます

効果的なプロンプトの作成

各ツールのパラメーターの説明には、Claude Code から最良の結果を得るための詳しいメッセージ作成のガイダンスが記載されています。主な原則は次のとおりです。

• 分析または作成してほしい内容を具体的に指定します
• Claude の注意を向けたいファイルパスやディレクトリを明記します
• 出力形式（箇条書き、JSON、コードスニペットなど）を指定します
• 制約条件と注目してほしい領域（パフォーマンス、セキュリティ、アクセシビリティなど）を含めます
• 再開ツールの場合：以前のコンテキストを参照し、段階的に作業を進めます

詳しいガイダンスと例については、ツールのパラメーターの説明をご覧ください。

公開

このプロジェクトでは、公開を自動化するために GitHub Actions を使用しています。

• リリース：GitHub リリースを作成すると、npm に自動で公開されます
• 手動：「Publish to npm」ワークフローのディスパッチを使用して手動で公開します

ライセンス

MIT

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

トラブルシューティング

Claude CLI が見つからない

• Claude CLI がインストールされており、PATH に含まれていることを確認します
• カスタムバイナリ名を使用する場合は、CLAUDE_CLI_NAME 環境変数を設定します
• CLI が動作することを確認します：claude --version

権限エラー

• 利用規約に同意するため、claude --dangerously-skip-permissions を一度実行します
• MCP サーバーに Claude CLI を実行する権限があることを確認します

会話の継続性に関する問題

• 各応答で応答 ID が返されます。会話を続けるために保存してください
• 長期間操作がないと、会話の有効期限が切れることがあります
• previousResponseId を指定せずに新しい会話を開始すると、最初から始まります
• 任意の過去の応答 ID から会話を分岐できます

非同期タスクに関する問題

• タスクは完了から 1 時間後に自動的にクリーンアップされます
• 実行時間の長いタスクの監視には status を使用します
• 必要に応じて cancel でタスクをキャンセルできます
• タスクが停止しているように見える場合は、デバッグログを確認します
• MCP サーバーが切断されると、タスクは自動的にキャンセルされます

システム通知

• macOS の通知では、タスクの開始（「Agent Task Started」）と完了（「Agent Task Completed」）が表示されます
• 開始時（Tink）と完了時（結果に応じて Glass／Basso／Funk）で異なるサウンドが鳴ります
• MCP_NOTIFICATIONS=false 環境変数を設定すると無効にできます
• 通知には、コンテキスト用に短縮されたプロンプトテキストが含まれます

パフォーマンスに関する考慮事項

• 非同期タスクは MCP サーバーをブロックしません
• 複数の非同期タスクを同時に実行できます
• リソースの枯渇を避けるため、タスクの進行状況を監視してください
• 非常に長時間かかる処理では、タスクのキャンセルを検討してください
• 親プロセスの監視により、孤立したプロセスの発生を防ぎます