Cursor MCP設定ガイド — mcp.jsonでサーバーに接続する手順

CursorでMCPサーバーに接続する設定は、.cursor/mcp.jsonまたは~/.cursor/mcp.jsonにJSONを書くだけで完結します。ローカルのコマンド起動型(stdio)とリモートのURL型(HTTP/SSE)で書式が変わり、OAuth認証が必要なサーバーには専用のauthフィールドを追加します。CursorをClaude Codeと併用する読者、あるいはCursorからの移行を検討している読者に向けて、設定例・環境変数の展開構文・よくあるつまずきをまとめます。

本記事はCursorを導入済みで、これからmcp.jsonを設定する読者を想定しています。stdioの例を動かすには、Node.js(npxコマンド)またはPythonがローカルに入っている必要があります。mcp.jsonはCursorが自動生成するファイルではなく、自分でディレクトリとファイルを新規作成して書き始めます。

Cursorのmcp.jsonとは何か

mcp.jsonとは、CursorがMCPサーバーに接続するときに読み込む設定ファイルです。中身はmcpServersというキー1つの直下に、サーバー名をキーにした設定オブジェクトを並べる形を取ります。

置き場所は2種類あり、どちらに置くかで反映範囲が変わります。

チームで同じツールを使う前提なら、プロジェクト直下の.cursor/mcp.jsonに書きます。個人の作業でどのプロジェクトからでも呼びたいツールは~/.cursor/mcp.jsonです。ファイルは自分で新規作成してよく、Cursor公式が配布するJSON Schemaは見当たりません。補完に頼らず、キー名は本記事の例をそのまま参考にします。MCP自体の仕組みはMCPとはで扱っているので、プロトコルの背景から知りたい場合はそちらを先に読みます。

mkdir -p .cursor
touch .cursor/mcp.json

ローカルサーバーをstdioで登録する手順

コマンドで起動するローカルサーバーは、type・command・args・envの4フィールドで設定します。Node.js製のサーバーをnpxで起動する例です。

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

Pythonスクリプトを直接起動する場合は、commandをpythonに変え、argsにスクリプトのパスを渡します。

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "python",
      "args": ["mcp-server.py"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

stdioサーバーで使えるフィールドは次の5つです。

リモートサーバーをHTTP/SSEで接続する設定

すでにサーバーとして動いているリモートのMCPサーバーには、commandの代わりにurlとheadersを使います。

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

Cursorが対応するトランスポートは3種類あり、実行環境と想定ユーザー数、認証方式がそれぞれ違います。

自分だけが使うツールをさっと動かすならstdioで十分です。チームで共有する、複数人が同時に叩く前提ならSSEかStreamable HTTPを選びます。

MCPプロトコルの拡張機能についても対応は広く、CursorはTools・Prompts・Resources・Roots・Elicitationをサポートしています。インタラクティブなUIを返すApps拡張にも対応済みです。Apps拡張はプログレッシブエンハンスメント方式です。Cursor側がUIを描画できない状況でも、ツール自体は通常のテキスト応答としてそのまま動きます。

OAuth認証が必要なサーバーの設定方法

FigmaやLinearのように、リダイレクトURLの事前登録を求めてくるプロバイダがあります。固定のClient IDを発行している場合や、動的クライアント登録(Dynamic Client Registration)に対応していない場合も同様です。こうしたケースでは、urlを持つサーバー設定にauthオブジェクトを追加します。

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "scopes": ["read", "write"]
      }
    }
  }
}

scopesを省略すると、Cursorは/.well-known/oauth-authorization-serverを参照して対応スコープを自動検出します。CLIENT_SECRETはプロバイダが確認用のシークレットを要求する場合だけ必要です。

コールバック先のリダイレクトURLはCursor側で固定されています。利用者がWebとデスクトップのどちらから認証するかに応じて、両方を登録しておきます。

サーバーの識別はOAuthのstateパラメータで行われます。そのため、この2つのURLはどのMCPサーバーに対しても共通で使い回せます。プロバイダ側のOAuthアプリ設定で両方のリダイレクトURIを許可リストに入れておくと、Web版・デスクトップ版のどちらで認証しても失敗しません。

CLIENT_IDとCLIENT_SECRETは直書きせず、次のように変数展開で環境変数から読み込むのが安全です。

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}"
      }
    }
  }
}

mcp.json内で環境変数を展開する構文

Cursorはcommand・args・env・url・headersの5フィールドで変数展開に対応しています。使える構文は5種類です。

プロジェクト内のスクリプトを絶対パスで指定する例です。

{
  "mcpServers": {
    "local-server": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    }
  }
}

リモートサーバーのヘッダーにトークンを埋め込む例です。

{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

.cursor/mcp.jsonはプロジェクト直下の普通のJSONファイルです。そのままGitで共有できます。ただしAPIキーをenvに直書きすると、リポジトリの履歴にそのまま残ります。${env:NAME}で環境変数名だけを書き、実際の値はシェルのプロファイルや各自の.envに置く運用にすれば、設定ファイル自体はチームで共有しつつ秘密情報だけ手元に残せます。

よくあるつまずきと対処

Cursorのマーケットプレイスに載っている公式プラグインは、サイドバーの「Customize」から「Add to Cursor」を押すだけでインストールとOAuth認証が完了します。コミュニティ製のサーバーはcursor.directoryから探します。mcp.jsonを自分で書くのは、マーケットプレイスに無い自作サーバーを動かしたいときと、起動オプションを細かく制御したいときです。

設定したサーバーが動かないとき、確認する点は次の4つです。

• サイドバーの「Customize」でトグルがオンになっているか: 無効化されたサーバーは読み込まれず、チャットの利用可能なツール一覧にも出ません
• Outputパネルのログ: Cmd+Shift+U(WindowsはCtrl+Shift+U)でOutputパネルを開きます。ドロップダウンから「MCP Logs」を選ぶと、接続エラー・認証エラー・サーバーのクラッシュを区別できます
• npm系サーバーのキャッシュ: 最新化したいときは、一度Customizeから削除してnpmキャッシュをクリアしてから再追加します
• 自作サーバーの再起動: ファイルを更新しただけでは反映されず、Cursor自体の再起動が案内されています

npm cache clean --force

1つのMCPサーバーが応答しなくても、他のサーバーの動作には影響しません。Cursorはサーバーごとに障害を分離する設計です。失敗したツール呼び出しは失敗として表示されるだけで、残りのサーバーはそのまま使えます。接続そのものが確立できないケースの切り分けは、MCPサーバーに接続できないときの切り分け手順でより詳しく扱っています。

会社支給のCursorで特定のMCPサーバーが動かせない場合は、自分の設定ミスより先にエンタープライズ側の制御を疑います。

Cursorはツール実行前に承認を求めるのが既定の挙動です。ツール名の横の矢印を押すと、渡される引数を確認できます。この承認フローはターミナルコマンドと同じRun Modeに従います。たとえば「Auto-review」モードでは、許可済みのMCPツールがそのまま実行され、それ以外だけが分類器を通ります。

MCP設定はツールによって何が違うか

CursorからClaude Codeへの移行、あるいは両方を併用する場合、同じmcpServersという見た目でも、ツールごとに設定ファイルの構造が違う点でつまずきやすいところです。

一番大きな違いはスコープの数です。Cursorはプロジェクトかグローバルかの2択ですが、Claude Codeはさらに「プロジェクト内だが自分だけ」というlocalスコープを持ちます。同じ名前のサーバーが複数の場所で定義されていても、local→project→user→プラグイン→claude.aiコネクターの優先順位で1つだけ接続します。Cursorのmcp.jsonにはこの優先順位の概念がありません。プロジェクト設定とグローバル設定に同名のサーバーがあるときの挙動は、公式ドキュメントに明記がありませんでした。

環境変数の展開構文にも互換性がありません。Cursor向けに書いた${env:API_KEY}はClaude Codeでは展開されず、Claude Code向けの${API_KEY}もCursorでは変数として認識されません。サーバー本体(npmパッケージやHTTPエンドポイントのURL)は共通して使い回せますが、mcp.jsonの中身は書き直しが必要です。

Cursorから移行する場合の設定の引き継ぎ方はCursorからClaude Codeへの移行ガイドにまとめています。Claude Code側のclaude mcp add構文とスコープの詳細はClaude Code MCP設定ガイドを参照してください。Claude Desktopのclaude_desktop_config.jsonはClaude Desktop MCP設定ガイドにまとめています。

まとめ

CursorのMCP設定は、.cursor/mcp.jsonか~/.cursor/mcp.jsonにmcpServersを書くだけで動き始めます。基本形は3パターンです。ローカルのコマンド起動型はcommand/args/env、リモートのURL型はurl/headers、OAuthが要るサーバーはさらにauthオブジェクトを足します。環境変数はハードコードせず${env:NAME}で外出しし、動かないときはまずCustomizeのトグルとMCP Logsを確認します。Claude CodeやClaude Desktopと併用するチームは、設定ファイルの形式が別物である前提で、サーバーごとに書き直す手間を見込んでおきます。

よくある質問

mcp.jsonに書いたAPIキーがGitの履歴に残らないようにできますか

envフィールドに値を直書きせず、${env:NAME}で環境変数名だけを書く方法があります。実際の値はシェルのプロファイルや各自のローカル.envに置けば、.cursor/mcp.json自体はチームでバージョン管理下に置いても、リポジトリにキーそのものは残りません。

1つのMCPサーバーをCursorとClaude Codeの両方で使い回せますか

サーバー本体が同じnpmパッケージやHTTPエンドポイントであれば、両方のツールから呼び出せます。ただし設定ファイルの形式が異なるため、mcp.jsonの中身自体は書き直しが必要です。キー名も環境変数の展開構文もスコープの考え方も別物です。

MCPサーバーが応答しないと他のツールも止まりますか

止まりません。Cursorはサーバーごとに障害を分離しています。1つのサーバーが失敗しても、そのツール呼び出しが失敗と表示されるだけで、他のMCPサーバーは通常どおり動作します。

MCPサーバーは画像を返せますか

返せます。サーバー側がbase64エンコードした画像をツールの応答に含めると、Cursorはチャットにその画像を添付表示します。モデルが画像入力に対応していれば、そのまま内容を解析します。

npm製のMCPサーバーをアップデートするにはどうすればいいですか

Customizeから一度サーバーを削除し、npm cache clean --forceでnpmキャッシュをクリアしてから再度追加すると最新版が入ります。自作の独自サーバーであれば、ローカルのファイルを更新したうえでCursorを再起動します。

機密情報を扱うMCPサーバーを追加しても安全ですか

条件付きで安全です。公式は4点を推奨しています。

• シークレットはenvに直書きせず、環境変数として渡す
• 機密性の高いサーバーは、複数人が同時に触れるSSE/Streamable HTTPでなくstdioでローカル実行する
• APIキーは必要最小限の権限に絞る
• 可能なら追加前にサーバーのソースコードを確認する