cursor-mcp

@qmediat.io/cursor-mcp

Cursor CLI（cursor-agent）用のMCP サーバーです。Model Context Protocolを通じて、プランで利用できる任意のモデル ID（Composer、Claude、GPT、Gemini、Grok の各ファミリー）でCursorのエージェントを実行します。

このサーバーを使う理由

• あらゆるCursorモデルに対応 — model IDは指定されたままcursor-agent --modelに渡されます。cursor_modelsでは、CLIで利用できるモデル（プランのComposer、Claude、GPT、Gemini、Grokの各ファミリー）を一覧表示します
• 5つのツール — エージェントの実行、セッションの継続、モデルの一覧表示、セッションの一覧表示、ヘルスチェック
• 並列実行 — 組み込みの並行処理制御（セマフォ）を使って、複数のモデルを同時に実行します
• 保護された実行 — シェルを介さずにspawnを実行し、自動承認はオペレーターの環境を通じてのみ行います（ツールのパラメーターでは指定できません）。クライアントによるキャンセルやタイムアウト時には、子プロセスとそのプロセスグループを終了します（SIGTERMを送信し、5秒後にSIGKILLを送信します。Windowsではcursor-agent本体のみ）
• 最小限の依存関係 — @modelcontextprotocol/sdkとzodのみ
• セッション管理 — 呼び出しをまたいで会話を再開できます

クイックスタート

前提条件

1. Node.js >= 22.0.0（開発時にはnpm run lintのBabel 8が必要なため、22.18または24.11が必要です）
2. Cursor CLIがインストールされ、認証済みであること：

# Install the Cursor CLI (installs `agent`; `cursor-agent` stays as a legacy alias — the one this server resolves)
curl https://cursor.com/install -fsS | bash

# Authenticate (a Cursor account whose plan includes agent usage — see cursor.com/docs/models-and-pricing)
agent login

Node.js 22以降が必要です。

インストール

claude mcp add --scope user cursor-cli -- npx -y @qmediat.io/cursor-mcp

または手動でインストールします（下記参照）。npm install -g @qmediat.io/cursor-mcpを実行するとcursor-mcpコマンドがインストールされ、任意の設定ファイルでnpxの行を置き換えられます。

設定

Claude Code（~/.claude.json）

{
  "mcpServers": {
    "cursor-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@qmediat.io/cursor-mcp"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "cursor-cli": {
      "command": "npx",
      "args": ["-y", "@qmediat.io/cursor-mcp"]
    }
  }
}

ローカル開発

{
  "mcpServers": {
    "cursor-cli": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/cursor-mcp/dist/index.js"]
    }
  }
}

環境変数

利用可能なツール

どちらのエージェントツールも --output-format stream-json を指定して cursor-agent を実行します。回答、session_id、request_id、cursor-agent が報告したモデル、所要時間、ツール呼び出し回数、変更されたファイル（書き込み／編集対象をそれぞれ 1 回ずつ）は、テキストと structuredContent（outputSchema を公開）で返されます。リクエストで進捗トークンを送信するクライアントには、イベント（モデル、ツール呼び出し、アシスタントメッセージ）ごとに notifications/progress が 1 つ送信されるため、10 分間の実行が応答なしに見えることはありません。

モデル

model は指定されたとおり cursor-agent --model に渡されるため、インストール済み CLI が受け付けるすべての ID を使用できます。最新の一覧と料金は cursor.com/docs/models-and-pricing に掲載されており、cursor_models は CLI が報告する内容（cursor-agent models）を返します。auto（デフォルト）を指定すると、Cursor がモデルを選択します。この README では意図的に ID を記載していません。Cursor ではこのパッケージのリリースよりも速いペースでモデルが追加・廃止されており、ここに一覧を載せたことで 1.0.x は現在のすべてのモデルを拒否するようになったためです。

モード

並列実行

ツール呼び出しを並列に行うことで、複数のモデルを同時に実行できます。

# In Claude Code, spawn 3 Agent subprocesses:
Agent 1: cursor_agent with model=<a Composer id from cursor_models> → "Review this code"
Agent 2: cursor_agent with model=<a Claude id from cursor_models> → "Review this code"
Agent 3: cursor_agent with model=<a GPT id from cursor_models> → "Review this code"

組み込みのセマフォ（デフォルト：3）は、レート制限エラーを防ぐため、上限を超えたリクエストをキューに入れます。

セキュリティ

• シェル実行なし — 引数配列を使った child_process.spawn を使用します。プロンプトの前には -- 区切り文字が付き、セッション ID は 1 語である必要があるため、どちらも cursor-agent のオプションとして解釈されることはありません（-f のプロンプトやセッション ID が --force に変わることはありません）。
• 認証情報を保存しない — OAuth は cursor-agent が処理します。
• HTTP リクエストなし — 純粋な CLI ラッパーであり、cursor-agent 以外へのネットワークアクセスはありません。
• プロセスのクリーンアップ — クライアントによるキャンセル（MCP リクエストのシグナル）とタイムアウトが、子プロセスとそのプロセスグループ内のヘルパーを終了させます（POSIX の場合。Windows ではプロセスグループがないため、cursor-agent 自体にのみシグナルが送られます）。まず SIGTERM を送り、CURSOR_KILL_GRACE_MS（5 s）経過後に SIGKILL を送ります。呼び出しと同時実行枠は、子プロセス自体が終了した場合にのみ解放されます。サーバーのシャットダウン時も、実行中のすべてのプロセスグループを同じ方法で終了させるため、サーバー終了後もエージェントが動作し続けることはありません。
• 自動承認には制限あり — --force には CURSOR_ALLOW_YOLO=true 環境変数の明示的な設定が必要で、LLM が制御することはできません。これが設定されていない場合、エージェントは変更を提案するだけです。CURSOR_SANDBOX=enabled を設定すると、自動承認されたエージェントの実行範囲を制限できます。この設定は cursor_agent と cursor_reply の両方に適用されます。
• 信頼済みワークスペース — 呼び出しごとに、指定された workspace（デフォルトではサーバーの作業ディレクトリ）に対して cursor-agent --trust を実行するため、エージェントがディレクトリについて確認を求めることはありません。workspace には、操作対象として意図したディレクトリのみを指定してください。
• 同時実行数を制限 — セマフォによってリソースの枯渇を防ぎます。

詳しくは SECURITY.md をご覧ください。

監督付きコーディングスキル

任意で使えるClaude Code スキルです。Claude Code がスーパーバイザーとして動作し、Cursor の任意のモデルにコーディングを任せられます。

仕組み： Claude Code がタスクを分析し、cursor_agent を通じて Cursor に明確な指示を送り、ディスク上の実際のファイルを読み取って出力を確認します。その後、納得できるまで cursor_reply で反復します（最大 3 ラウンド）。

前提条件： まず、cursor-cli MCP サーバー（このパッケージ）を Claude Code にインストールして設定する必要があります。

使い方

/cursor-code <task>                              # default: auto (Cursor chooses)
/cursor-code --model <id> <task>                 # any id cursor_models lists

cursor_models を実行して、CLI で利用できる ID を一覧表示します。

スキルをインストールする

mkdir -p ~/.claude/skills/cursor-code

以下の内容で ~/.claude/skills/cursor-code/SKILL.md を作成します。

---
name: cursor-code
description: Delegate coding to any Cursor model while Claude Code supervises.
  Use when user says "cursor-code", "delegate to cursor", "cursor code this",
  or "/cursor-code". Works with any model id cursor_models lists (the Composer,
  Claude, GPT, Gemini and Grok families on your Cursor plan).
metadata:
  version: 1.1.0
---

# Supervised Coding: Claude Code (Supervisor) -> Cursor (Coder)

You are the **supervisor** (Claude Code). A Cursor model is the **coder**.
You give precise instructions, the coder writes code, you review and iterate.

## Parsing

Extract from user input:
- `--model <id>` -> model to use (default: `auto`, Cursor chooses)
- Everything else -> the task description

If user says a model name naturally (e.g. "use composer", "with gemini", "z grok"),
extract it and map to an id from cursor_models.

## Workflow

### Step 1: Analyze
- Read the relevant files to understand current state
- Break the user's task into a single, focused coding instruction
- Identify: target files, constraints, acceptance criteria

### Step 2: Instruct
Call `cursor_agent` with:
- `model`: extracted model or `auto`
- `workspace`: current working directory
- `prompt`: precise instruction with file paths, function names, constraints
- Keep prompt focused -- one task per call, not an entire feature
- Extract and store the `session_id` from the response for use in Step 4

Output before calling: `[cursor-cli -> <model>]`

### Step 3: Verify
After the coder returns:
- Run `git diff --name-only` to discover ALL files the coder modified
- Read EVERY modified file from disk (use Read tool) -- not just the ones from your prompt
- Diff against expectations
- Check: correctness, edge cases, security, type safety

### Step 4: Iterate (max 3 rounds)
If issues found:
- Call `cursor_reply` with the same session_id
- Give specific fix instructions (file:line, what's wrong, what to do)
- Re-verify after each round
- If the coder is fundamentally off-track (wrong approach, not just small bugs),
  abandon the session early and start fresh with a more explicit prompt

### Step 5: Report
Summarize to the user:
- Model used (confirm from response, not just request)
- What was done
- Files changed
- Rounds needed (1 = clean, 2-3 = corrections applied)
- Any manual fixes Claude Code applied directly

## Rules
- ONE task per cursor_agent call -- don't batch entire features
- ALWAYS read files from disk after coder finishes
- NEVER trust cached file contents -- Cursor writes directly to disk
- Set timeout_seconds appropriately (30-120s for typical tasks)
- If the task is trivial (< 5 lines) -- just do it yourself, don't delegate
- Follow model transparency rules -- always state [cursor-cli -> model] before call
- If cursor_agent/cursor_reply fails (timeout, auth, CLI not found) -- report the error to the user and run cursor_health to diagnose. Do not retry silently
- If unsure about valid model IDs -- call cursor_models first

スキルファイルを作成した後、Claude Code を再起動します。

開発

git clone https://github.com/qmediat/cursor-mcp.git
cd cursor-mcp
npm install
npm run build
npm run lint   # structure rules, repeated blocks, the baseline ratchet (docs/SYSTEMIC.md §1)
npm run format # Prettier (npm run lint checks it)
node dist/index.js

ガイドラインについてはCONTRIBUTING.mdを参照してください。npm test でビルドが行われ、スモークテストと argv テストが実行されます。

商標と提携関係

Cursor は Anysphere の商標です。これは Quantum Media Technologies sp. z o.o. が公開・保守する、独立したコミュニティ運営の統合機能であり、Anysphere との提携、支援、承認を受けたものではありません。このサーバーを通じた Cursor API または CLI の使用には、Anysphere 独自の利用規約と、ご自身の API キーまたはアカウントが適用されます。

ライセンス

MIT - Quantum Media Technologies sp. z o.o.

Quantum Media Technologies が制作 · qmediat のその他のオープンソースプロジェクト