MCP Server Manager for Cursor

Cursor 用 MCP サーバーマネージャー

Cursor 用の MCP（Model Context Protocol）ワークスペースマネージャーです。このプロジェクトは、ローカルの開発環境で複数の MCP サーバーを管理する、煩雑になりがちなワークフローを簡素化します。一貫性のある統合設定方法と CLI（コマンドラインインターフェース）を提供し、すべての MCP サーバーを一括または個別に起動、停止、更新し、ステータスを確認できます。また、mcp.json にあるグローバル（またはローカル）の Cursor MCP 設定も自動的に管理します。

deno task コマンド（例：deno task start）を使って CLI を実行するか、メインモジュールを直接実行して deno run -A src/mod.ts <command> [options] を使うことができます。

プロジェクトの概要

目的

それぞれに固有のセットアップや運用上の注意点があるさまざまな MCP サーバーの管理は、手間がかかることがあります。このプロジェクトは、その管理を一元化します。すべてのサーバーを一度定義すれば、シンプルなコマンドで制御できます。MCP サーバーが HTTP/SSE または STDIO を介して通信する場合でも、このマネージャーで一貫して管理できます。

はじめに

注意

MCP を初めて使いますか？ 特に企業環境では、何をしているのか理解しておく必要があります。先に進む前に、MCP を安全に使う方法をお読みください。

MCP Server Manager を使い始めるには、主にサーバー定義と環境設定を操作します。主要なコンポーネントの概要は次のとおりです。

• サーバー設定ファイル：servers/ ディレクトリにある TypeScript ファイル（例：mcp-myservice.config.ts）で、各 MCP サーバーのプロパティを定義します。テンプレートとして examples/ ディレクトリのファイルを利用できます（例：HTTP/SSE サーバー向けの examples/mcp-atlassian.ts.example、STDIO サーバー向けの examples/mcp-slack.ts.example）。
• 環境変数：機密性の高い認証情報やサーバー固有の設定は、.env ファイル（例：servers/config/mcp-myservice.env）に保存します。参考として、サンプルの環境ファイル（例：examples/mcp-myservice.env.example）が examples/ ディレクトリに用意されています。
• グローバルマネージャー設定：servers/config/main.env ファイルで、ENABLED_SERVERS 変数による有効なサーバーの指定など、グローバルな動作を制御します。

新しいサーバーの作成と設定について、詳しい手順を確認するには、「メインワークフロー」の新しい MCP サーバーの追加セクションをご覧ください。

ヒント

最適に利用するには、このリポジトリをフォークして、個人用 MCP サーバーの設定を安全に管理してください。CLI に簡単にアクセスするには、src/mod.ts を PATH に登録するエイリアスを設定するか、他のプロジェクトで src/mod.ts を参照する Cursor ルールを作成してください。

MCP サーバーとは？

Model Context Protocol（MCP）サーバーは、Cursor と外部サービスやツールとの橋渡し役です。標準化された一連の「ツール」を公開することで、Cursor がこれらのサービス（Jira、Slack、Confluence など）のデータや機能にアクセスし、利用できるようにします。これにより、自然言語や特定のコマンドを使って、IDE から直接 Jira の課題を取得したり、Confluence のページを検索したり、Slack メッセージを送信したりできます。

状態管理

MCP Server Manager は、設定済みサーバーのステータス（例：HTTP サーバーが現在実行中かどうか）を追跡し、その状態を data/state.json に保存します。このファイルは CLI によって自動的に管理されます。

メインワークフロー

新しい MCP サーバーの追加

1. 設定ファイルを作成する：
   • examples/ ディレクトリに移動し、テンプレートを選択します：
     • HTTP/SSE サーバーの場合：mcp-atlassian.ts.example
     • STDIO サーバーの場合：mcp-slack.ts.example
   • 選択したテンプレートファイルを servers/ ディレクトリに複製します。
   • コピーしたファイルの名前を、新しいサーバーを表すものに変更します。例：mcp-myservice.config.ts。
2. 設定を編集する：
   • 新しいサーバーの設定ファイル（例：mcp-myservice.config.ts）を開きます。
   • name、description、type（http または stdio）、image、args の各フィールドを更新します。
   • 環境ファイル（例：servers/config/mcp-myservice.env）は、設定したサーバーの name に基づいて MCP マネージャーによって自動的に使用されます。
   • HTTP/SSE サーバーの場合：
     • 固定ポートを指定するには、任意で args 配列に --port PORT を含めることができます。
     • ポートを指定しない場合、サーバーの起動時にマネージャーが利用可能なポートを自動的に割り当てます。
   • サーバーのヘルスチェック方法を定義するには、healthValidator セクションを設定します。この標準化された設定は、HTTP と STDIO の両方のサーバーで機能します。以下に例を示します：

     healthValidator: {
       method: "mcp/tools/list", // 呼び出す MCP メソッド
       params: {},               // メソッドのパラメーター
       responseContains: "tools", // レスポンスに含まれている必要がある任意の文字列
       timeoutMs: 5000           // タイムアウト（ミリ秒）
     }
     

   • サーバーの起動後にテストする方法をユーザーに案内するため、postStartInstructions プロパティにテスト用プロンプトの例を含めます。
3. 環境ファイルを作成する：
   • 必須の環境変数をプレースホルダー値とともにすべて記載した環境ファイルの例を examples/ に作成します（例：examples/mcp-myservice.env.example）。
   • 実際の環境ファイルを servers/config/ ディレクトリに作成します（例：servers/config/mcp-myservice.env）。例のファイルをコピーし、実際の認証情報と設定を入力します。
   • 重要：実際の環境ファイルが servers/config/*.env のような一般的なパターンで対象になっていない場合は、機密性の高い認証情報をコミットしないよう、.gitignore に追加してください。
4. テストする：
   • 一般的なワークフロー（起動するには deno task start など）を使って、新しいサーバーを管理できるようになりました。

HTTP サーバー設定の例：

const serverConfig: McpServerConfig = {
  name: 'mcp-atlassian',
  description: 'MCP Atlassian Connector',
  type: 'http',
  image: 'ghcr.io/sooperset/mcp-atlassian:latest',
  args: [
    '--transport',
    'sse',
    // Port will be automatically assigned if not specified
    // '--port',
    // '9000',
    '-vv',
  ],

  healthValidator: {
    method: 'mcp/tools/list',
    params: {},
    responseContains: 'tools',
    timeoutMs: 5000,
  },

  postStartInstructions: `
Atlassian MCP server is now running!
You can now use Jira and Confluence tools in Cursor.
Make sure your Atlassian credentials are properly configured in your .env file.
Try using the jira_list_projects tool to retrieve all the Jira projects I have access to and format the output as a bulleted list
`,
}

STDIO サーバー設定の例：

const serverConfig: McpServerConfig = {
  name: 'mcp-slack',
  description: 'MCP Slack Connector',
  type: 'stdio',
  image: 'mcp/slack',
  args: [], // No additional args needed for STDIO servers
  // The orchestrator will add the necessary Docker args

  healthValidator: {
    method: 'slack_get_users',
    params: { limit: 1 },
    timeoutMs: 10000,
  },

  postStartInstructions: `
NOTE: The Slack MCP server is designed to run in interactive mode.
Cursor will run the server as needed, so no persistent container is needed.
You can now use Slack tools in Cursor.
Try using the command: List all channels in the Slack workspace
`,
}

MCP サーバーの編集

既存の MCP サーバーを編集するには：

1. servers/ 内の設定ファイルを変更します。
2. 必要に応じて、対応する環境ファイルを servers/config/ 内で更新します。 次回コマンドを実行したとき（例：deno task start）に変更が反映されます。

MCP サーバーの削除

MCP サーバーを削除するには：

1. servers/ から設定ファイルを削除します。
2. （任意）環境ファイルを servers/config/ および examples/ から削除します。 そのサーバーは CLI による管理対象ではなくなります。

一般的なワークフロー（CLI コマンド）

すべてのコマンドは、設定済みのすべてのサーバーを対象に実行することも、--server=<server-name> フラグを使って特定のサーバーを対象に実行することもできます（例：deno task start --server=mcp-atlassian）。

• サーバーを起動する：

  deno task start
  # or to start a specific server:
  deno task start --server=mcp-myservice
  

  このコマンドは、設定済みの MCP サーバーを起動します。HTTP サーバーの場合は Docker コンテナを起動し、設定でポートが指定されていなければ、使用可能なポートを自動的に割り当てます。STDIO サーバーの場合は、設定を検証します。起動に成功すると、CLI はサーバー設定で Cursor の設定ファイルを自動更新するかどうかを確認します。更新しない場合は、手動で追加できるよう、必要な JSON 設定を表示します。

  # To see how the Cursor MCP config would change without making changes:
  deno task start --dry-run
  # or for a specific server:
  deno task start --server=mcp-myservice --dry-run
  # dedicated dry-run task:
  deno task start:dry-run
  

  --dry-run フラグを使うと、実際には変更を加えずに、Cursor の MCP 設定ファイルに加えられる変更を確認できます。現在の設定と、サーバー起動後の設定内容が表示されます。

• サーバーを停止する：

  deno task stop
  # or to stop a specific server:
  deno task stop --server=mcp-myservice
  

  実行中の HTTP MCP サーバーコンテナを停止します。STDIO サーバーは継続して実行されないため、このコマンドは主に HTTP タイプに作用します。サーバーが実行されていない状態を反映するよう、CLI が Cursor の設定ファイルを自動更新し、Cursor と実際のサーバー状態の同期を維持します。

  # To see how the Cursor MCP config would change without making changes:
  deno task stop --dry-run
  # or for a specific server:
  deno task stop --server=mcp-myservice --dry-run
  # dedicated dry-run task:
  deno task stop:dry-run
  

  起動コマンドと同様に、--dry-run フラグを使うと、実際には変更を加えたりサーバーを停止したりせずに、Cursor の MCP 設定ファイルに加えられる変更を確認できます。

• サーバーのステータスを確認する：

  deno task status
  # or for a specific server:
  deno task status --server=mcp-myservice
  

  設定済みのすべての MCP サーバーの現在のステータス（実行中、停止中、STDIO の検証ステータスなど）を表示します。

• サーバーのログを表示する：

  deno task logs
  # or for a specific server:
  deno task logs --server=mcp-myservice
  

  実行中の HTTP MCP サーバーコンテナから、直近 100 行のログを表示します。問題のトラブルシューティングや、サーバーの動作状況の監視に役立ちます。

  # To continuously stream logs in real-time:
  deno task logs --stream
  # or for a specific server:
  deno task logs --server=mcp-myservice --stream
  # dedicated streaming task:
  deno task logs:stream
  

  --stream フラグを使うと、docker logs --follow と同様に、ログをリアルタイムでストリーミングできます。問題のデバッグや、サーバーの動作状況をリアルタイムで確認する際に特に役立ちます。ストリーミングを終了するには、Ctrl+C を押してください。

• ヘルスチェックを実行する：

  deno task health-check
  # or for a specific server:
  deno task health-check --server=mcp-myservice
  

  HTTP サーバーの場合は、実行中のコンテナが応答し、正常な状態であるかを確認します。STDIO サーバーの場合は、検証を再実行します。

• サーバーのイメージを更新する：

  deno task update
  # or for a specific server:
  deno task update --server=mcp-myservice
  

  設定ファイルで指定されたサーバーの最新の Docker イメージを取得します。

MCP サーバーの種類

このマネージャーは、設定内の type プロパティによって区別される、次の 2 種類の MCP サーバーをサポートしています。

1. HTTP/SSE サーバー（例：Atlassian MCP）

• このコードベースでの動作：
  • これらのサーバーは、バックグラウンドで永続的な Docker コンテナとして実行されます。
  • このマネージャーは Docker コンテナを起動し、必要なポートをマッピングして、標準化された healthValidator 設定を使ってヘルスチェックを実行します。
  • 認証とサーバー固有のロジックは Docker イメージ内で処理され、サーバーに関連付けられた .env ファイルから渡される環境変数によって設定されます。
• Cursor の設定：
  • Cursor は URL（例：http://localhost:9000/sse）を使ってこれらのサーバーに接続します。
  • サーバー設定の args にポートを指定すると、マネージャーはそのポートを使用します。
  • ポートが指定されていない場合、サーバーの起動時に使用可能なポートが自動的に割り当てられます。
  • サーバーの起動に成功すると、CLI は適切な設定を使って Cursor の MCP 設定ファイルを自動更新するかどうかを確認します。
  • 手動で設定する場合、CLI は Cursor の設定に追加する正確な JSON スニペットを提示します。

2. STDIO サーバー（例：Slack MCP）

• このコードベースでの動作：
  • これらのサーバーは、Cursor によって必要に応じて起動され、標準入力／出力（STDIO）を介して通信するように設計されています。
  • 常駐するバックグラウンドサービスとしては実行されません。STDIO サーバーで deno task start コマンドを使用すると、このマネージャーは healthValidator 設定を使用して、.env ファイルに記載された設定と認証情報が正しいかどうかを検証する目的でのみ、Docker コンテナを一時的に起動します。その後、コンテナは終了します。これは想定された動作です。
• Cursor の設定：
  • STDIO サーバーの Cursor 設定には、コンテナを対話形式で実行するための command（例：docker）と args 配列が含まれます。
  • マネージャーは --env-file フラグを自動的に追加し、環境ファイルを指定するため、認証情報を設定にハードコードする必要はありません。
  • 検証に成功すると、CLI は適切な設定で Cursor の MCP 設定ファイルを自動的に更新するかどうかを提示します。
  • 手動で設定する場合、CLI は Cursor 用の JSON スニペットのテンプレートを提示します。

ヘルス検証

HTTP サーバーと STDIO サーバーの両方で、標準化されたヘルス検証メカニズムを使用できます。

healthValidator: {
  method: "mcp/tools/list",    // MCP method to call
  params: {},                  // Parameters for the method
  responseContains: "tools",   // Optional string that must be in the response
  timeoutMs: 5000              // Timeout in milliseconds
}

• healthValidator プロパティは省略可能です。指定されていない場合（null、false、または undefined）、ヘルスチェックはスキップされ、成功ステータスになります。
• 設定すると、バリデーターは指定されたメソッドとパラメーターを使って JSON-RPC 2.0 リクエストを構築します。
• HTTP サーバーの場合、リクエストはサーバーのエンドポイントに送信されます。
• STDIO サーバーの場合、リクエストは Docker STDIO を介してサーバーに送信されます。
• レスポンスにエラーがないか確認し、必要に応じて特定の文字列が含まれているかも確認します。
• この統一された方法により、サーバーの設定が簡素化され、すべてのサーバータイプで一貫したヘルスチェックが可能になります。

ヘルス検証システムは、ヘルスチェックをスキップする際のログメッセージを抑制するために、バリデーターに渡せる silent オプションにも対応しています。これは主に、詳細なログ出力が不要な状況で CLI がサーバーのステータスを確認する際に、内部的に使用されます。

高レベルアーキテクチャ

MCP Server Manager は、設定主導のアプローチで設計されています。

• サーバー設定（servers/*.config.ts）：これらの TypeScript ファイルがシステムの中核です。各ファイルでは、次のプロパティを持つ単一の MCP サーバーを定義します。
  • name：サーバーの一意の識別子
  • description：人が読みやすい説明
  • type：http または stdio
  • image：使用する Docker イメージ
  • args：コマンドライン引数（HTTP サーバーの場合は、--port パラメーターを含みます）
  • healthValidator：ヘルスチェック用の任意の設定
  • postStartInstructions：サーバー起動後にユーザーに表示する指示。使用例のコマンドを含みます
• 環境ファイル（servers/config/*.env および examples/*.env.example）：認証情報とサーバー固有の設定は、メイン設定とは別の .env ファイルに保存されます。これにより、機密データがバージョン管理に含まれないようにできます。
• コアロジック（src/）：
  • mod.ts：CLI のメインエントリーポイントです。
  • config.ts：servers/ ディレクトリからすべてのサーバー設定を読み込みます。
  • types.ts：サーバー設定（McpServerConfig など）と状態に関する TypeScript の型とインターフェースを定義します。
  • orchestrator.ts：サーバー設定を Cursor の MCP エントリーに変換する transformServerConfigForCursor 関数が含まれています。
  • commands/start.ts：引数を解析して処理を統括する、メインの start コマンドロジックを実装します。
  • commands/stop.ts、commands/status.ts、commands/health-check.ts：それぞれの処理のロジックを実装します。
  • services/cursor-service.ts：Cursor の MCP 設定ファイルの読み込みと書き込みを管理します。
  • services/docker-service.ts：Docker CLI とのすべてのやり取り（イメージの取得、コンテナの実行と停止、状態の確認）を処理します。
  • services/health-validator-service.ts：HTTP サーバーと STDIO サーバーの両方に対応する、標準化されたヘルス検証のロジックが含まれています。
• Deno タスク（deno.jsonc）：一般的な CLI コマンド（deno task start など）を簡単に実行するためのショートカットを提供します。

ユーザーは主に、servers/ 内の設定ファイルと、それに対応する .env ファイルを操作します。src/ ディレクトリには、これらすべてを動作させる基盤の仕組みが含まれています。

トラブルシューティング

• ログを確認する：CLI では、参考になるログが表示されます。より詳細な出力を確認するには、servers/config/main.env の LOG_LEVEL を調整してください。
  • サーバー固有のログを確認するには、logs コマンドを使用します：deno task logs --server=mcp-myservice。または、deno task logs --stream を使用してログをリアルタイムでストリーミングできます。
  • コンテナログに直接アクセスできます。コンテナログには、エラーの詳細やデバッグ情報が含まれていることがよくあります。
• servers/config/main.env：このファイルには、MCP マネージャー自体のグローバル設定が含まれています。
  • DENO_ENV：より詳細な出力や、開発環境固有の動作が必要な場合は、development に設定します。
  • LOG_LEVEL：ログの詳細度を制御します。debug、info、warn、error を設定できます。トラブルシューティングでは、debug が役立つことがよくあります。
  • ENABLED_SERVERS：管理対象として利用可能にするサーバー名をカンマ区切りで指定します。例：ENABLED_SERVERS=github-mcp-server, mcp-atlassian, mcp-slack。指定しない場合、servers/ ディレクトリ内のすべてのサーバーが有効になります。これにより、設定ファイルを削除せずにサーバーを選択的に有効化または無効化できます。
  • CURSOR_MCP_CONFIG_PATH：MCP サーバー用の Cursor 設定を保存するファイルパスを指定します。デフォルトでは、グローバルな Cursor 設定ファイル（例：~/.cursor/mcp.json）が指定されています。プロジェクトごとに MCP 設定を管理する場合は、現在のプロジェクトのワークスペース内にある .cursor/mcp.json など、プロジェクト固有のパスに変更できます。このパスは、サーバー起動時に Cursor 設定を自動更新するために使用されます。
• Docker の問題：
  • Docker がインストールされ、実行中であることを確認してください。CLI も確認を試みますが、手動で確認すると確実です。
  • HTTP サーバーが起動に失敗した場合や、正常に動作していない場合は、docker ps でコンテナが実行中か確認し、docker logs <container_name>（例：docker logs mcp-atlassian）でログを調べてエラーがないか確認してください。
• 環境変数：サーバー固有の .env ファイル（例：servers/config/mcp-atlassian.env）の名前と保存場所が正しく、servers/config/ ディレクトリ内にあり、MCP サーバーのイメージに必要な正しい認証情報と設定が含まれていることを確認してください。
• サーバーが見つからないエラー：--server フラグを使用した際に、サーバーが有効になっていないというエラーが表示される場合は、servers/config/main.env の ENABLED_SERVERS 変数にそのサーバー名が記載されていることを確認してください。
• Cursor 設定の問題：自動設定が機能しない場合は、CURSOR_MCP_CONFIG_PATH 環境変数が正しく設定され、有効なファイルの場所を指定していることを確認してください。デフォルトのパスは ~/.cursor/mcp.json ですが、オペレーティングシステムや Cursor のインストール方法によって異なる場合があります。

Cursor 設定の同期

MCP Server Manager は、Cursor の MCP 設定ファイルを実際のサーバー状態と同期します。

• サーバーが動的に割り当てられたポートで起動すると、ポートが状態ファイルと Cursor の設定の両方に保存されます。
• サーバーが停止すると、Cursor の設定がオフライン状態を反映するように更新されます。
• サーバー設定（引数、コマンドなど）が変更されると、Cursor の設定が自動的に更新されます。
• 設定ファイルのパスは、servers/config/main.env の CURSOR_MCP_CONFIG_PATH 環境変数によって決まります。

これにより、ポートが変更されたり、サーバーが起動・停止したりしても、Cursor は MCP サーバーに関する最新情報を常に保持できます。