Cursor Agent MCP

🚀 Cursor Agent MCP Server

このサーバーは、cursor-agent CLIをラップした最小限で強化されたModel Context Protocol (MCP) サーバーです。Claudeに友好的なツールを複数提供し、チャット、リポジトリ分析、コード検索、計画立案などの機能を実現します。

核心実装: cursor-agent-mcp/server.js テストハーネス: cursor-agent-mcp/test_client.mjs パッケージマニフェスト: cursor-agent-mcp/package.json

🚀 クイックスタート

このサーバーを使用することで、Claude Codeなどのホストから重い「思考」やリポジトリ関連のタスクをcursor-agent CLIにオフロードできます。具体的な手順や使用方法は以下のセクションを参照してください。

✨ 主な機能

• 「バーブ中心」のCLIをモデルにしたマルチツールインターフェイス
• Claude Codeや他のMCPホストでも良好に動作
• 安全なプロセス生成 (シェルを使用せず) と堅牢なタイムアウト処理
• ホスト内でのデバッグを容易にするためのオプションのプロンプトエコー
• 環境変数を通じた設定可能なデフォルト値 (モデル、強制実行、タイムアウト、実行可能ファイルのパス)
• シングルショットチャット用の下位互換性のあるレガシーツール

📦 インストール

1. このリポジトリをクローンまたはダウンロードします。

2. MCPサーバーの依存関係をインストールします。

cd ./cursor-agent-mcp
npm ci        # または: npm install

3. cursor-agent CLIがインストールされ、PATHに含まれていることを確認します (またはCURSOR_AGENT_PATHを設定します)。

cursor-agent --version

4. MCPサーバーを起動します。

# サーバーディレクトリから
node ./server.js

# またはリポジトリのルートから提供されたスクリプトを使用
npm --prefix ./cursor-agent-mcp run start

npxは必要ですか？

いいえ。このサーバーはリポジトリから直接実行され、npmに公開されていません (package.jsonで"private": trueが設定されています)。上記のように依存関係をインストールした後、Nodeを使用してserver.jsを実行してください。

将来的にこれをnpmパッケージとして公開し、package.jsonにbinエントリを追加した場合、npxを使用して実行でき、MCPホストをその実行可能ファイルに向けることができます。それまでは、ここに示されているNodeベースのコマンドを使用することをお勧めします。

💻 使用例

基本的な使用法

# ツールをリストし、プロンプトでチャットを呼び出す
node ./cursor-agent-mcp/test_client.mjs "Hello from smoke test"

# --helpでrawツールを実行する (暗黙の--printなし)
TEST_TOOL=cursor_agent_raw TEST_ARGV='["--help"]' node ./cursor-agent-mcp/test_client.mjs

高度な使用法

{
  "name": "cursor_agent_chat",
  "arguments": { "prompt": "Explain SIMD in one paragraph", "output_format": "markdown" }
}

📚 ドキュメント

目的: Claude Codeでのトークン使用量とコストの削減

このMCPは、重い「思考」やリポジトリ関連のタスクをホスト (例: Claude Code) からcursor-agent CLIにオフロードするために存在します。CLIに対象を絞ったプロンプトベースの指示で分析/計画/検索を行わせることで、以下のことができます。

• 必要なファイル/パスのみに作業を限定し、ワークスペース全体をストリーミングする必要をなくします。
• 環境変数 (または呼び出しごと) を介して費用対効果の高いモデルを選択し、ホストのコンテキストを小さく保ちます。
• output_format ("text" | "markdown" | "json") とカスタマイズされたプロンプトを通じて応答の詳細度を制御します。
• 一般的なチャットではなく、ターゲット指向の出力を生成する専用ツール (analyze, search, plan, edit) を使用します。

コストコントロールのヒント

• 正確なスコープを選択する:
  • cursor_agent_search_repoでinclude/excludeグロブを使用し、cursor_agent_analyze_filesで精選されたpathsを使用します。
• 意図的に出力形式を選択する:
  • 簡潔な回答には"text"または"markdown"を使用します。構造化された出力が本当に必要な場合のみ"json"を予約します (通常はより大きい)。
• タスクに合ったモデルを選択する:
  • CURSOR_AGENT_MODELを費用対効果の高いデフォルトに設定し、必要な場合のみツール呼び出しごとに上書きします。
• 不要なエコー/デバッグを避ける:
  • CURSOR_AGENT_ECHO_PROMPT=1はセットアップ中に役立ちますが、後で無効にしてホストログのトークンを節約します。
  • 通常の使用ではDEBUG_CURSOR_MCPをオフにしておきます。これは診断情報をstderrに書き込みます (ホストのトークンにはカウントされませんが、ノイズが多い)。
• 実行時間を制御する代わりにアイドル時の終了を避ける:
  • CURSOR_AGENT_IDLE_EXIT_MS="0"に設定して、有効な実行が生成途中で切断されないようにします。CURSOR_AGENT_TIMEOUT_MSと対象を絞ったプロンプトでコスト/時間を制限します。
• cursor_agent_rawを慎重に使用する:
  • これは強力で、詳細なセッションをストリーミングできます。最も安価な使用方法として、簡潔なプロンプトと"text"出力を持つ対象を絞ったツールを使用することをお勧めします。

ツール

これらのツールはJavaScript.server.tool()以降で登録されています。すべてのツールは「COMMON」引数を共有します。

• output_format: "text" | "json" | "markdown" (デフォルト "text")
• extra_args?: string[]
• cwd?: string
• executable?: string
• model?: string
• force?: boolean
• echo_prompt?: boolean → 結果に「Prompt used: …」を先頭に追加する

1) cursor_agent_chat

• 引数: { prompt: string, ...COMMON }
• 動作: プロンプトを最後の位置引数として渡してシングルショットチャットを行います。
• コードパス: JavaScript.server.tool() → JavaScript.runCursorAgent()

2) cursor_agent_edit_file

• 引数: { file: string, instruction: string, apply?: boolean, dry_run?: boolean, prompt?: string, ...COMMON }
• 動作: プロンプトベースのラッパー。エージェントにファイルを編集またはパッチを提案させる構造化された指示を構築します。
• コードパス: JavaScript.server.tool()

3) cursor_agent_analyze_files

• 引数: { paths: string | string[], prompt?: string, ...COMMON }
• 動作: 着目するパスをリストしたプロンプトベースのリポジトリ/ファイル分析を行います。
• コードパス: JavaScript.server.tool()

4) cursor_agent_search_repo

• 引数: { query: string, include?: string | string[], exclude?: string | string[], ...COMMON }
• 動作: オプションのinclude/excludeグロブを使用して、リポジトリ全体でプロンプトベースのコード検索を行います。
• コードパス: JavaScript.server.tool()

5) cursor_agent_plan_task

• 引数: { goal: string, constraints?: string[], ...COMMON }
• 動作: プロンプトベースの計画ツールで、目標に対する番号付きの計画を返します。
• コードパス: JavaScript.server.tool()

6) cursor_agent_raw

• 引数: { argv: string[], print?: boolean, ...COMMON }
• 動作: 生のargvをCLIに転送します。--printを追加しないようにprint=falseがデフォルトです。print=trueに設定すると注入されます。
• コードパス: JavaScript.server.tool()

7) cursor_agent_run (レガシー)

• 引数: { prompt: string, ...COMMON }
• 動作: 元のシングルショットチャットラッパーで、互換性のために維持されています。
• コードパス: JavaScript.server.tool()

MCPホストの設定例

Claude Code/Claude Desktopのエントリ例:

{
  "mcpServers": {
    "cursor-agent": {
      "command": "node",
      "args": ["/abs/path/to/cursor-agent-mcp/server.js"],
      "env": {
        "CURSOR_AGENT_ECHO_PROMPT": "1",
        "CURSOR_AGENT_FORCE": "true",
        "CURSOR_AGENT_PATH": "/home/you/.local/bin/cursor-agent",
        "CURSOR_AGENT_MODEL": "gpt-5",
        "CURSOR_AGENT_IDLE_EXIT_MS": "0",
        "CURSOR_AGENT_TIMEOUT_MS": "60000"
      }
    }
  }
}

オプション: デバッグログを有効にする

DEBUG_CURSOR_MCP=1を追加すると、診断情報がstderrに出力されます (生成されたargv、プロンプトのプレビュー、終了情報)。統合中またはトラブルシューティング中に役立ちます。

{
  "mcpServers": {
    "cursor-agent": {
      "command": "node",
      "args": ["/abs/path/to/cursor-agent-mcp/server.js"],
      "env": {
        "CURSOR_AGENT_ECHO_PROMPT": "1",
        "CURSOR_AGENT_FORCE": "true",
        "CURSOR_AGENT_PATH": "/home/you/.local/bin/cursor-agent",
        "CURSOR_AGENT_MODEL": "gpt-5",
        "CURSOR_AGENT_IDLE_EXIT_MS": "0",
        "CURSOR_AGENT_TIMEOUT_MS": "60000",
        "DEBUG_CURSOR_MCP": "1"
      }
    }
  }
}

Claude内での使用方法

• 上記のいずれかのツールを呼び出します。引数は「ツール」セクションのJSONフィールドと1対1で対応します。
• 正確なプロンプトを表示するには、グローバルにCURSOR_AGENT_ECHO_PROMPT=1を設定するか、ツール呼び出しで"echo_prompt": trueを渡します。
• 高度な使用法では、argvと印刷動作を正確に制御するためにcursor_agent_rawを使用することをお勧めします。

トラブルシューティング

• 「cursor-agent not found」
  • CURSOR_AGENT_PATHをCLIの絶対パスに設定するか、PATHに含まれていることを確認します。
• 「No prompt provided for print mode」
  • print=trueでRAWを呼び出したが、プロンプトが提供されていません。argvにプロンプトを提供するか、print=falseに設定します。
• 生成途中での早期終了
  • CURSOR_AGENT_TIMEOUT_MSを増やし、CURSOR_AGENT_IDLE_EXIT_MSを"0"に維持します。
• ツールの出力が空
  • プロバイダーの資格情報とモデル名を確認します。argv: ["--version"]でcursor_agent_rawを試して、CLIの正常性を確認します。

開発

• サーバーを直接起動する:
  • node ./cursor-agent-mcp/server.js
• スモーククライアント:
  • node ./cursor-agent-mcp/test_client.mjs "hello"
  • TEST_TOOL=cursor_agent_raw TEST_ARGV='["--help"]' node ./cursor-agent-mcp/test_client.mjs
• 開発中に有用な環境変数:
  • DEBUG_CURSOR_MCP=1 CURSOR_AGENT_ECHO_PROMPT=1

主要なエントリポイント

• エグゼキューター: JavaScript.invokeCursorAgent()
• レガシーランナー: JavaScript.runCursorAgent()
• ツール登録の開始: JavaScript.server.tool()

セキュリティに関する注意事項

• 子プロセスはshell: falseで生成され、シェルインジェクションや引用符の問題を避けます。
• 入力はZodで検証され、未知の型は拒否されます。
• シークレットをログに記録しないでください。DEBUGはargvと最小限の環境コンテキストのみを出力します。

バージョニング

現在のサーバーバージョン: 1.1.0 (詳細は cursor-agent-mcp/package.json を参照)

📄 ライセンス

MIT (詳細は cursor-agent-mcp/package.json を参照)

謝辞

• Model Context ProtocolチームによるMCPプロトコルとSDK
• gemini-mcp-toolなどのマルチバーブMCPサーバーからのインスピレーション