Naumu

@naumu/mcp

Naumu 用の MCP サーバーです。Claude Code、Cursor、その他の AI エージェントからナレッジグラフにアクセスできます。

このリポジトリは、公開済みの @naumu/mcp パッケージの公開拠点です。ドキュメント、イシュー、リリースを掲載しています。開発は Naumu モノレポで行われます。バグを見つけた場合やツールの追加を希望する場合は、イシューを作成してください。

Naumu は、次の 2 つのトランスポートで MCP を利用します。

1. OAuth を使ったリモート接続（https://naumu.ai/api/mcp）— 推奨される方法です。ブラウザーからサインインするため、API キーを作成、貼り付け、同期する必要はありません。このパッケージは使用しません。
2. ローカル stdio（このパッケージ）— npx で必要に応じて起動し、API キーで認証します。CI ジョブ、ボットや外部エージェントの ID、旧式の stdio 専用ハーネスなど、ブラウザー OAuth に対応していないクライアントで使用します。

推奨セットアップ：OAuth を使ったリモート MCP

サーバーを一度登録します。セッションで初めて Naumu ツールを使用すると、ブラウザーが開き、サインインしてアクセスを承認するよう求められます。その後は、すべてのセッションでツールを利用できます。

Claude Code

claude mcp add --transport http --scope user naumu https://naumu.ai/api/mcp

--scope user を指定すると、現在のプロジェクトではなくマシン全体にサーバーが登録されるため、リポジトリごとに登録を繰り返す必要はありません。

Cursor

{
  "mcpServers": {
    "naumu": {
      "url": "https://naumu.ai/api/mcp"
    }
  }
}

OAuth クライアント ID とシークレットの欄は空欄のままにします。Naumu が Dynamic Client Registration（DCR）を使って、サインイン時にクライアントを自動登録します。

リモートサーバーに対応するその他の MCP 対応クライアントも、同じように https://naumu.ai/api/mcp を指定し、サインインはブラウザーに任せます。バックエンドのアドレスではなく、フロントエンドのオリジン（naumu.ai）を使用してください。サインインと同意には、フロントエンドのオリジンに保存されている Naumu セッションが必要です。

Naumu の Settings > Your agents にある Active access リストから、接続済みツールのアクセス権をいつでも取り消せます。

詳しい手順については、ローカル MCP をご覧ください。

フォールバックのセットアップ：API キーを使ったローカル stdio サーバー

ブラウザー OAuth に対応していないクライアント（CI、ボット、外部エージェントの ID、または stdio のみを扱うハーネス）では、このパッケージを使用します。

1. API キーを取得する

1. Naumu の Settings > Your agents を開きます。
2. Create an API key を選択し、用途がわかる名前（対象のツール名など）を付けます。
3. キーをすぐにコピーします。キーは一度しか表示されず、後から取得できません。キーは nmu_ で始まります。

キーが漏えいした場合の影響をそのキーだけに限定できるよう、ツールごとに別のキーを使用してください。

2. クライアントを設定する

このパッケージをグローバルにインストールする必要はありません。クライアントが npx を使って必要に応じて起動します。

Claude Code

claude mcp add naumu -s user \
  -e NAUMU_API_KEY=nmu_your_key_here \
  -- npx -y -p @naumu/mcp naumu-mcp

Cursor

{
  "mcpServers": {
    "naumu": {
      "command": "npx",
      "args": ["-y", "-p", "@naumu/mcp", "naumu-mcp"],
      "env": {
        "NAUMU_API_KEY": "nmu_your_key_here"
      }
    }
  }
}

環境変数

変数	必須	デフォルト	説明
NAUMU_API_KEY	はい	-	API キー（nmu_ で始まります）
NAUMU_API_URL	いいえ	https://naumu.ai	Naumu API のベース URL。設定する必要はありません

利用可能なツール

どちらのトランスポートでも、同じツールを利用できます。bot と記されたツールは、ボット ID のキー（nmu_bot_*）にのみ登録されます。ボット ID には、ID の権限に基づいてフィルタリングされたツールも追加で提供されます。

スペースとメンバー

ツール	説明
naumu_list_graphs	キーからアクセスできるすべてのスペース（グラフ）を、ID、名前、ロールとともに一覧表示します
naumu_create_graph	認証済みユーザーが所有する、新しい空のスペースを作成します
naumu_list_members	スペースのメンバーと各自のロールを一覧表示します
naumu_whoami	呼び出し元のキーが誰のものか（ユーザー、またはグラフと許可されたツールを持つボット ID）を返します

スキーマ

ツール	説明
naumu_get_schema	スペースのスキーマ（ノードタイプ、属性、接続）を取得します
naumu_update_schema	スキーマを新しい定義全体で置き換えます
naumu_add_node_type	スキーマ全体を再送信せずに、ノードタイプを1つ追加します
naumu_add_connection	既存のノードタイプから別のノードタイプへの接続を1つ追加します
naumu_add_attribute	既存のノードタイプに属性を追加または拡張します
naumu_list_schema_violations	スキーマに照らしてスペースを監査し、違反を報告します

グラフの読み取り

ツール	説明
naumu_search	グラフのノードを対象に、意味とテキストを組み合わせた検索を行います
naumu_filter	タイプと属性でノードをフィルタリングし、決定的かつ漏れのない結果を返します
naumu_get_node	プロパティ、エッジ、メモ、スレッド、生成されたコンテキストとともに、ノードを1つ取得します
naumu_list_node_connections	1つのノードの接続を一覧表示します
naumu_list_dense_nodes	子ノード数に基づき、接続が過剰なハブノードを見つけます
naumu_ask	@Naumu に質問し、ノードに基づいた、出典と信頼度を含む統合された回答を取得します

グラフへの書き込み

ツール	説明
naumu_add_node	1回の呼び出しで1～25個のノードを作成します
naumu_update_node	既存のノードのプロパティを上書きします
naumu_remove_node	ノードとそのすべての接続を削除します（破壊的操作）
naumu_add_edge	既存のノード間に1～25個のエッジを作成します
naumu_remove_edge	（source、target、label）で特定したエッジを1つ削除します
naumu_remove_edges_bulk	1回のアトミックな呼び出しで1～100個のエッジを削除します
naumu_reparent	ノードの親エッジをアトミックに入れ替えます
naumu_batch_reparent	1～25個のノードを共通の新しい親に付け替えます
naumu_delegate	@Naumu に非同期で実行するタスクを委任します。ポーリング用の threadId が返されます

スレッドとトピック

ツール	説明
naumu_list_threads	最終アクティビティ順にスレッドを一覧表示し、isParticipant フラグを付けます
naumu_get_thread	人間とボットの参加者一覧とともに、スレッドを1つ取得します
naumu_read_thread	スレッドのメッセージを読み取ります。各メッセージには processing または complete のステータスが付いています
naumu_post_message	参加しているスレッドに Markdown メッセージを投稿します
naumu_create_thread	bot 新しい会話を開始し、参加者を追加して、最初のメッセージを投稿します。必要に応じてトピックに分類できます
naumu_add_reaction	メッセージに絵文字リアクションを追加します（冪等）
naumu_remove_reaction	メッセージに付けた自分のリアクションを削除します
naumu_typing	スレッドで「入力中」インジケーターを表示または非表示にします
naumu_list_topics	topicIds で使用する、スペースのトピック（分類先）を一覧表示します
naumu_create_topic	トピックを作成します。管理者のみ実行でき、名前は小文字のスラッグである必要があります

メモ

ツール	説明
naumu_create_note	メモを作成します。同じ呼び出しで Markdown 本文全体を指定することもできます
naumu_note_read	メモの現在の Markdown と、メモに関連付けられたノードを読み取ります
naumu_note_append	Markdown ブロックをメモの末尾に追加します
naumu_note_insert	名前付き見出しの直後に Markdown を挿入します
naumu_note_replace_section	名前付き見出しの下の本文を置き換えます
naumu_note_delete_section	見出しとその本文を削除します（破壊的操作）
naumu_note_replace	メモ全体の内容を置き換えます（破壊的操作）
naumu_note_find_replace	メモ内の文字列をリテラル検索して置換します

添付ファイル

ツール	説明
naumu_request_attachment_upload	ファイルをアップロードするための署名付き S3 URL を取得し、その後 attachmentIds を使って参照します
naumu_get_attachment	attachmentId でチャットの添付ファイルを読み取ります
naumu_persist_canvas_attachment	キャンバスに関連付けられた保留中の添付ファイルを永続化します

スペースへの参加

ツール	説明
naumu_admission_status	スペースに自動参加できる人と、承認待ちの人を表示します
naumu_whitelist_members	メールアドレスをホワイトリストに登録し、その人たちがサインイン時に自動参加できるようにします
naumu_resolve_admission	リポジトリの .naumu ファイルで参照されているスペースに参加（または参加をリクエスト）します
naumu_resolve_join_request	保留中の参加リクエストを承認または拒否します

ChatGPT との互換性

OpenAI MCP のインターフェースでは、search と fetch という名前のツールが必要です。これらは、スペース横断検索とノードの読み取りを、クライアントが想定するレスポンス形式で提供します。

ツール	説明
search	アクセス可能なすべてのスペースを検索します。{ results: [{ id, title, url }] } を返します
fetch	search で返されたノードを取得します。{ id, title, text, url } を返します

トラブルシューティング

stdio サーバーの設定に誤りがあると、MCP ハンドシェイクの前に終了します。ほとんどのクライアントでは、エラーも表示されず、サーバーがまったく表示されません。組み込みのセルフチェックを実行して、原因を確認してください。

npx -y -p @naumu/mcp naumu-mcp doctor

このチェックでは、順に NAUMU_API_KEY が設定されていること（キー自体は表示されません）、API に接続でき、キーが受け入れられること、そしてこのビルドが最新の公開バージョンと一致していることを確認します。チェックごとに 1 行と判定結果を出力し、失敗があればゼロ以外のステータスで終了します。

naumu-mcp doctor (v0.11.1, API https://naumu.ai)

[fail] API key: NAUMU_API_KEY is missing from the environment
[warn] API: reachable (https://naumu.ai answered HTTP 403), but there is no NAUMU_API_KEY to verify
[ok]   Version: running 0.11.1 (npm latest)

Verdict: 1 check failed - the MCP server will not work until this is fixed.
Most likely fix: Set NAUMU_API_KEY - create a key at https://naumu.ai/settings (Settings > Your agents > Create an API key)

MCP クライアントと同じ環境で実行してください。そうしないと、キーのチェック対象がクライアントの設定ではなく、シェルになります。

ライセンス

MIT