Novu MCP

Novu MCP サーバー

メインの GitHub リポジトリを見る »

✨ 機能

Novu ワークスペース全体を AI エージェントから利用できるようにする、単一の MCP サーバーです。

• エージェント — Novu エージェントの作成、一覧表示、確認、更新ができるほか、チャネル接続を Novu CLI のプレイブックに引き継げます
• 会話 — エージェントのスレッドを一覧表示し、アクティビティのタイムライン（メッセージ、承認、MCP 接続）を確認できます
• 通知 — イベントを取得・フィルタリングし、実行ログと配信ステータスをすべて確認できます
• サブスクライバー — メールアドレス、電話番号、名前、ID で受信者を検索・管理できます
• ワークフロー — 通知ワークフローの一覧表示、確認、作成、更新、トリガーができます
• 設定 — サブスクライバーのチャネル設定（メール、SMS、アプリ内、プッシュ、チャット）を読み取り、更新できます
• 環境 — 環境とその設定を確認できます
• インテグレーション — 各チャネルのプロバイダーインテグレーションを管理できます
• 認証とアイデンティティ — whoami で認証情報（OAuth または API キー）を検証し、アクティブなリージョンを確認できます

🚀 クイックスタート

サーバーをホストする必要はありません。サーバーは完全に管理されています。Novu Cloud のリージョンに対応するエンドポイントを選び、MCP クライアントの接続先として指定してください。

リージョン	エンドポイント	Novu API
米国	https://mcp.novu.co/	api.novu.co
EU	https://eu.mcp.novu.co/	eu.api.novu.co

各ホストはリージョンに固定された専用のデプロイメントです。?region= クエリパラメーターはもうありません。（後方互換性のため、ホストのリージョンと一致しない ?region= を指定すると、正しいエンドポイントを案内する 400 が返されます。）

認証

サーバーは2つの認証方法に対応しており、どちらも地域別エンドポイントで同じように機能します。

1. OAuth（推奨） — コピー＆ペーストする API キーは不要です。MCP クライアントが最初に接続すると、サーバーは 401 と、クライアントを Novu の認可サーバー（Clerk）に誘導する OAuth ディスカバリードキュメント（/.well-known/oauth-protected-resource）を返します。クライアントで Novu のサインインと同意の画面が開き、組織を選択すると、アクセス トークンがクライアントに自動的に届きます。

リモート OAuth に対応する MCP クライアント（Cursor、Claude、ChatGPT、Windsurf など）なら、このフローは自動的に処理されます。ヘッダーを指定せず、サーバー URL を追加するだけです。

注：クライアントは user:org:read スコープ（ディスカバリードキュメントで通知されます）を要求する必要があります。これにより Novu API が組織を特定できます。Novu アカウントが複数の組織に属している場合は、同意時にいずれかを選択するよう求められます。

2. API キー — Novu Dashboard から取得したキーをベアラートークンとして指定します。

Authorization: Bearer <your-novu-api-key>

API キーを指定すると、サーバーはセッションを API キーモードとして扱い、ホスト型エンドポイントでも OAuth サインインフローを開始しません。キーは単一の環境（つまり単一の地域）に紐付けられているため、追加の設定は不要です。アカウントがある地域のエンドポイントに接続するだけです。

Novu をセルフホストしていますか？ OAuth は Novu Cloud（US/EU）でのみ利用できます。このフローは Novu Cloud の認可サーバーに対して実行されますが、セルフホスト型のデプロイメントからはアクセスできません。セルフホスト型のデプロイメントでは、常に API キーで認証します。独自インスタンスのデプロイとローカル開発を参照してください。

🎯 環境

リクエストがどの Novu 環境に送られるかは、認証方法によって異なります。

• API キー — キー自体が単一の環境に紐付けられているため、リクエストは常にその環境に対して実行されます。
• OAuth — トークンは組織に紐付けられ、Novu API はデフォルトでDevelopment環境を使用します。

OAuth セッションでは、各ツールで任意の environmentId パラメーターを指定して、対象の環境を選択できます（Novu API への Novu-Environment-Id ヘッダーとして転送されます）。まず get_environments を呼び出して環境を一覧表示し、対象の環境の _id を指定します。たとえば、Production の通知を確認できます。Novu API は、その環境が組織に属していることを検証します。API キーの場合、このパラメーターは無視されます。キーによってすでに環境が固定されているためです。

ローカル／セルフホスト型 API — この MCP サーバーを別の場所で稼働している Novu API（たとえば http://localhost:3000 のセルフホスト型インスタンス）に接続するには、.dev.vars で NOVU_API_URL を設定し、サーバーをローカルで実行します（ローカル開発を参照）。これは以前の ?region=local クエリパラメーターに代わるものです。セルフホスト環境では常に API キーを使用します。OAuth は Novu Cloud でのみ利用できます。

🛠️ 使用方法

サーバーは https://mcp.novu.co/（US）および https://eu.mcp.novu.co/（EU）で、Streamable HTTP MCP トランスポートを使用します。

Cursor、Windsurf、Claude およびその他の OAuth 対応クライアント

OAuth によるリモート MCP サーバー接続に対応するクライアントなら、ヘッダーなしで接続できます。サインインフローはクライアントが処理します。

• URL（US）： https://mcp.novu.co/
• URL（EU）： https://eu.mcp.novu.co/

初回接続時に、クライアントで Novu のサインインと同意の画面が開きます。承認して組織を選択すると、ツールが自動的に表示されます。

API キー（mcp-remote／stdio クライアント、セルフホスト型 Novu）

stdio トランスポートのみをサポートするクライアント、静的な API キーを使用する場合、または OAuth を利用できないセルフホスト型 Novuインスタンスを実行している場合は、Authorization ヘッダーを指定して mcp-remote プロキシを使用してください。API キーを指定すると、クライアントは OAuth フローを開始しません。

{
  "mcpServers": {
    "novu": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.novu.co/",
        "--header",
        "Authorization:Bearer your-novu-api-key"
      ]
    }
  }
}

EU 地域の場合は、URL を https://eu.mcp.novu.co/ に置き換えてください。

📦 利用可能なツール

ツール	説明
whoami	認証済みユーザー（Novu API に対する認証情報を検証）とアクティブなリージョンを表示します
create_agent	エージェントを作成します（デフォルトはマネージドのデモ用 Claude で、API キーは不要です）
connect_agent	既存のエージェントにチャネルを接続するための CLI 手順を返します
get_agents	カーソルページネーションを使用してエージェントを一覧表示します
get_agent	識別子を指定して単一のエージェントを取得します
update_agent	エージェントの名前、ステータス、ブリッジ URL、または動作を更新します
get_conversations	エージェントの会話を一覧表示します（エージェント、サブスクライバー、ステータス、プロバイダーで絞り込み可能）
get_conversation_activities	会話のタイムラインを確認します（簡潔なデバッグダイジェスト。生の JSON を表示するには verbose を指定します）
get_environments	すべての環境と、その詳細および API キーを一覧表示します
get_notifications	チャネル、テンプレート、サブスクライバー、日付などで絞り込んでイベントを取得します
get_notification	特定の通知を詳細な実行ログとともに取得します
find_subscribers	メールアドレス、名前、電話番号、または ID でサブスクライバーを検索します
get_subscriber_preferences	すべてのチャネルとワークフローにわたるサブスクライバーの設定を取得します
update_subscriber_preferences	サブスクライバーのチャネル設定を全体またはワークフローごとに更新します
get_workflows	すべてのワークフローと基本情報を一覧表示します
get_workflow	ワークフローの完全な定義、ステップ、ペイロードスキーマを取得します
trigger_workflow	カスタムペイロードを指定して、サブスクライバー向けにワークフローを実行します
get_integrations	チャネル間で設定されているプロバイダー連携を一覧表示します

💻 ローカル開発

前提条件： Node.js 20 以降、および pnpm。

# Clone and install
git clone https://github.com/novuhq/novu-mcp-server.git
cd novu-mcp-server
pnpm install

# Start the local worker
pnpm dev

サーバーは http://localhost:8787 で起動します。ホスト版と同じ方法で、MCP クライアントの接続先に指定してください。

{
  "mcpServers": {
    "novu": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/",
        "--header",
        "Authorization:Bearer your-novu-api-key"
      ]
    }
  }
}

設定は .dev.vars（Git で無視されます）から読み込まれます。まずは .dev.vars.example をコピーしてください。主な変数は次のとおりです。

• NOVU_API_URL — このサーバーがプロキシする Novu API（セルフホスト型 API の場合は http://localhost:3000、クラウドの場合は https://api.novu.co または https://eu.api.novu.co など）。
• NOVU_REGION — whoami に表示されるリージョン名。
• CLERK_OAUTH_ISSUER — OAuth 用の Clerk 認可サーバーです。空にすると OAuth が完全に無効になり、API キーのみで動作します（セルフホストモード）。

http://localhost:3000 で稼働するセルフホスト型 Novu APIを使ってローカル開発する場合は、.dev.vars で NOVU_API_URL="http://localhost:3000" を設定し、インスタンスの API キーを使用してください（OAuth は Novu Cloud でのみ利用できます）。

{
  "mcpServers": {
    "novu-local": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/",
        "--header",
        "Authorization:Bearer your-local-novu-api-key"
      ]
    }
  }
}

ローカル開発での OAuth

ローカルで OAuth を試すには、.dev.vars の CLERK_OAUTH_ISSUER に、Novu API が信頼する Clerk 認可サーバー（米国の場合は https://clerk.dashboard.novu.co など）を設定します。MCP エンドポイントのオリジンはリクエスト URL から導出されるため、開発サーバーを起動し、同じ URL（例：http://localhost:8787/）を MCP クライアントの接続先に指定してください。RFC 9728 では、PRM の resource フィールドが MCP エンドポイント URL と完全に一致する必要があります。サーバーがバインドされているものと異なるホストまたはポート経由で接続すると、Cursor などのクライアントはメタデータを破棄し、user:org:read スコープを登録せずに接続します。

CLERK_OAUTH_ISSUER が空の場合、OAuth ディスカバリーエンドポイントは 404 を返し、401 応答には OAuth メタデータが含まれません。そのため、クライアントは API キー認証に切り替わります。

独自のインスタンスをデプロイする

このサーバーは標準的な Cloudflare Worker です。wrangler.jsonc は、 トップレベルの設定をローカル開発専用（routes がないため、wrangler dev は localhost でサービスを提供し、OAuth ディスカバリーでは localhost のオリジンが 通知されます）とし、実際のデプロイ先は名前付き環境の下に配置する構成です。

• pnpm deploy → --env us（mcp.novu.co をバインドし、NOVU_API_URL=https://api.novu.co を設定します）
• pnpm deploy:eu → --env eu（eu.mcp.novu.co をバインドし、NOVU_API_URL=https://eu.api.novu.co を設定します）

独自のインスタンスをデプロイするには、リポジトリをフォークし、独自の routes、NOVU_API_URL、NOVU_REGION を設定した環境を env の下に追加するか、 既存の環境を編集してから、wrangler deploy --env <name> でデプロイします。セルフデプロイした インスタンスは、NOVU_API_URL が指す先に対する API キー認証で、そのまま動作します。 セルフホストされた Novu API も利用できます。独自のデプロイで OAuth を使うには、 Novu API が信頼する認可サーバーを指定して CLERK_OAUTH_ISSUER シークレットを設定します （wrangler secret put CLERK_OAUTH_ISSUER --env <name>）。API キーのみを使う場合は、 この設定を行わないでください。

スクリプト

• pnpm dev — Wrangler を使って Worker をローカルで実行します（トップレベルの、ルート設定のない構成）
• pnpm deploy — US Worker をデプロイします（mcp.novu.co、--env us）
• pnpm deploy:eu — EU Worker をデプロイします（eu.mcp.novu.co、--env eu）
• pnpm type-check — TypeScript の型チェックを実行します
• pnpm lint:fix — Biome でリンターの問題を修正します
• pnpm format — Biome でコードベースをフォーマットします

プロジェクト構成

src/
├── index.ts            # Worker entry — auth extraction and routing
├── oauth.ts            # OAuth discovery, 401 bootstrap, initialize-time probe
├── server/NovuMCP.ts   # Durable Object hosting the MCP agent
├── tools/              # One file per tool group (workflows, subscribers, …)
├── utils/              # API client, validation, tool factory
└── types/              # Shared TypeScript types

src/tools/ の下に register*Tools 関数を作成し、src/server/NovuMCP.ts で登録することで、新しいツールを追加できます。

🔒 セキュリティ

• このサーバーは純粋な OAuth パススルーです。トークンの発行、交換、再署名は行いません。 トークンを独自に検証することもありません。Novu の Clerk 認可サーバーを通知し、 呼び出し元の Authorization ヘッダーをそのまま Novu API に転送します。トークンの検証と 組織・権限の解決は Novu API が行います。
• OAuth アクセストークン（Clerk の不透明な oat_… トークン）は有効期間が短く、 Novu 側で失効させることもできるため、長期間有効な API キーよりはるかに安全です。
• OAuth トークンでも従来の API キーでも、認証情報は MCP セッションに限定されます。 ランタイムの props チャネルを通じてセッションの Durable Object に渡され、 リクエストログに漏れる可能性のある URL に入れられることはありません。また、セッション終了時に 破棄されます。サーバーが共有の認証情報を保持することはありません。
• API キーや発行者の設定を絶対にコミットしないでください。ローカルの値には .dev.vars を 使用してください（すでに gitignore に登録されています）。
• Novu API キーはパスワードのように扱ってください。漏えいした疑いがある場合は、 ダッシュボードからローテーションしてください。

🤝 コントリビューション

1. 変更を加える

   git checkout -b feat/your-change
   pnpm dev           # Test locally
   pnpm type-check    # Verify types
   git commit -m "feat: your change"
   git push origin feat/your-change
   

2. プルリクエストを作成する

   • feat:、fix:、docs:、chore: のいずれかを接頭辞にした、内容が分かりやすいタイトルを付けてください
   • 変更内容の簡単な説明と、該当する場合はツール呼び出しのサンプルを記載してください

ガイドライン：

• ツールの説明は簡潔にしてください。説明はそのまま LLM に表示されます
• src/utils/ の Zod スキーマを使って入力を検証してください
• 標準的な CRUD エンドポイントには ToolFactory ヘルパーを優先して使用してください
• 必要な機能がありませんか？GitHub issue を作成してください

サポートが必要ですか？ [email protected] にメールするか、Discord に参加してください。

---

コントリビューションありがとうございます！ 🙏