Anytype MCP Server

Anytype MCP サーバー

Anytype MCP サーバーは、AI アシスタントが自然言語を通じて Anytype の API とシームレスにやり取りできるようにする Model Context Protocol (MCP) サーバーです。

Anytype の OpenAPI 仕様を MCP ツールに変換することで、AI と Anytype の強力な機能の間をつなぎ、会話を通じてナレッジベースを管理できるようにします。

機能

• グローバル検索とスペース検索
• スペースとメンバー
• オブジェクトとリスト
• プロパティとタグ
• タイプとテンプレート

クイックスタート

1. API キーを取得する

1. Anytype を開きます
2. アプリの設定に移動します
3. API Keys セクションを開きます
4. Create new ボタンをクリックします

npx -y @anyproto/anytype-mcp get-key

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

Claude Desktop、Cursor、Windsurf、Raycast など

<YOUR_API_KEY> を実際の API キーに置き換えてから、以下の設定を MCP クライアントの設定に追加します：

{
  "mcpServers": {
    "anytype": {
      "command": "npx",
      "args": ["-y", "@anyproto/anytype-mcp"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <YOUR_API_KEY>\", \"Anytype-Version\":\"2025-11-08\"}"
      }
    }
  }
}

ヒント： Anytype で API キーを作成した後、API Keys セクションから API キーが入力済みの設定スニペットをコピーできます。

Claude Code（CLI）

<YOUR_API_KEY> を実際の API キーに置き換えてから、次のコマンドを実行して Anytype MCP サーバーを追加します：

claude mcp add anytype -e OPENAPI_MCP_HEADERS='{"Authorization":"Bearer <YOUR_API_KEY>", "Anytype-Version":"2025-11-08"}' -s user -- npx -y @anyproto/anytype-mcp

npm install -g @anyproto/anytype-mcp

{
  "mcpServers": {
    "anytype": {
      "command": "anytype-mcp",
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <YOUR_API_KEY>\", \"Anytype-Version\":\"2025-11-08\"}"
      }
    }
  }
}

カスタム API ベース URL

デフォルトでは、サーバーは http://127.0.0.1:31009 に接続します。anytype-cli（ポート 31012）やその他のカスタムベース URL を使用する場合は、ANYTYPE_API_BASE_URL を設定します：

{
  "mcpServers": {
    "anytype": {
      "command": "npx",
      "args": ["-y", "@anyproto/anytype-mcp"],
      "env": {
        "ANYTYPE_API_BASE_URL": "http://localhost:31012",
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <YOUR_API_KEY>\", \"Anytype-Version\":\"2025-11-08\"}"
      }
    }
  }
}

claude mcp add anytype \
  -e ANYTYPE_API_BASE_URL='http://localhost:31012' \
  -e OPENAPI_MCP_HEADERS='{"Authorization":"Bearer <YOUR_API_KEY>", "Anytype-Version":"2025-11-08"}' \
  -s user -- npx -y @anyproto/anytype-mcp

やり取りの例

Anytype では、次のようなやり取りができます：

• 「'Project Ideas' という名前で、説明が 'A space for storing project ideas' の新しいスペースを作成して」
• 「'Project Ideas' スペースに、タイトルが 'Research AI trends' の 'Task' タイプの新しいオブジェクトを追加して」
• 「タイトルを 'Dive deep into LLMs' にして、期限を3日後に設定し、自分に割り当てた2つ目のタスクを作成して」
• 「次に、タイトルが "Tasks for this week" のコレクションを作成し、2つのタスクをそのリストに追加して。最初のタスクの期限を今日から10日後に設定して」

ツールの動作と API バージョン

サーバーは、起動時に OpenAPI ドキュメントを 1 つ読み込みます。標準設定では、まず /v2/docs/openapi.json を試します。このエンドポイントが 404 または 410 を返す場合は、同じサーバー上の /docs/openapi.json にフォールバックします。旧バージョンのアプリはここで v1 を提供します。これにより、v2 が利用可能な場合は v2 が選択され、レガシー API のみを備えたアプリもサポートされます。

"args": ["-y", "@anyproto/anytype-mcp"]

レガシー v1 API を明示的に使用するには、バージョン指定の仕様を選択してください。

"args": ["-y", "@anyproto/anytype-mcp", "run", "http://127.0.0.1:31009/v1/docs/openapi.json"]

バージョン指定の /v2/docs/openapi.json URL も、v2 を明示的に選択する場合に引き続き利用できます。

明示的に指定した仕様の URL とローカルファイルは、指定どおりに使用され、フォールバックは行われません。認証の失敗、サーバーエラー、接続の失敗、JSON の形式不正が発生した場合も、別の API を選択せずに起動に失敗します。ラッパーは、選択したドキュメントで宣言されたルートを、バージョンプレフィックスを書き換えずに使用します。

検出は MCP プロセスごとに 1 回実行されます。ツールの呼び出しでは、解析済みの仕様と HTTP クライアントが再利用され、OpenAPI を再取得することはありません。新たに利用可能になった API バージョンを検出するには、Anytype の更新後に MCP サーバーを再起動してください。仕様の永続キャッシュは使用しません。

ツールの説明には操作に関するガイダンスが含まれます。呼び出しが失敗した場合は、isError: true、取得できる場合は HTTP ステータス、API のコード、メッセージ、問題、ヒントを含む API エラーが返されます。

サーバーは、提供する説明文の中で、自身の操作を OpenAPI の operationId で表記します。MCP ツール一覧と、get_schema または get_op_schema のレスポンスに含まれるフィールド説明では、これらの名前はこのラッパーのツール名として再表記されます（list_properties は API-list-properties になります）。修正ヒントは異なります。サーバーは、名前を挙げる各操作を REST ルートとして表記し、型付きの see_also 参照として一覧表示します。そのため、ラッパーはそのルートのテキストをツール名と引数に置き換え、参照に tool と args を付加します。リテラル値は書き換えられません。enum 値、example 値、op 名、endpoint 文字列、出力スキーマは、サーバーでの表記がそのまま維持されます。また、OpenAI と Anthropic のツールエクスポートでも、operationId によるツール名がそのまま使われます。

v1 でのオブジェクト作成、更新、削除、チャット作成が成功すると、ID、スペース ID、名前、アーカイブ状態、および利用可能な場合は型の識別情報を含む、簡潔な object レシートが返されます。ラッパーは、エコーバックされたマークダウン、スニペット、プロパティ値、アイコン、完全な型定義を省略します。警告、生成された ID、etag／再試行のメタデータは保持されます。必要に応じてオブジェクトを読み込み、内容を取得してください。v2 はすでに簡潔な作成／編集レシートを返すため、警告のヒントを再表記し、参照に tool と args を追加する以外は、そのまま渡されます。読み取り、検索、エラーについても、完全な API レスポンスが保持されます。

共有ツールポリシーは、入力とリクエストのルーティングを制御します：

• Authorization と Anytype-Version は OPENAPI_MCP_HEADERS から取得されます。
• expected_etag は If-Match に対応します。オブジェクトが変更されて上書きされるのを防ぐため、前回の読み取りで取得した etag を使用してください。ラッパーは前提条件の失敗時に再試行したり、前提条件を削除したりしません。レスポンスの etag は、取得できる場合、別の request_metadata テキストブロックで返されます。
• request_key は、このヘッダーが宣言されているエンドポイントで Idempotency-Key に対応します。新しい書き込みでは省略してください。ラッパーが一意のキーを生成し、request_metadata またはエラーの request_key で返します。同じ書き込みを再試行する場合に限り、再利用してください。ドキュメントが同一でも、呼び出しが別であれば生成されるキーは異なります。自動再試行はありません。OPENAPI_MCP_HEADERS のグローバルな Idempotency-Key は拒否されます。
• 既存の呼び出し元では、従来の引数名 If-Match と Idempotency-Key も引き続きそのまま使用できます。新しい名前と並べて案内されることはありません。エイリアスの値が競合する場合は拒否されます。
• ページネーション、フィールド選択、dry_run、create_missing_options、スキーマの検出は引き続き利用できます。
• ペアリングと API キー管理は対象外です。v2 の auth_whoami は、現在の認証情報の権限を確認するために引き続き利用できます。レスポンスにベアラートークンは含まれません。
• イベントストリームツールは、範囲が定まったツールの結果を生成しないため対象外です。チャットメッセージの取得には、メッセージ一覧表示ツールを使用してください。
• ファイルのダウンロードは、バイナリーアダプターを介してサポートされます。ツールはバイト列をプライベートな一時ディレクトリにストリーミングし、path、filename、media_type、size を返します。このパスは、MCP を実行しているマシンまたはコンテナー上のローカルパスです。ダウンロードに成功したファイルは、削除するか、オペレーティングシステムによってクリーンアップされるまでその場所に残ります。中断されたダウンロードは削除されます。Range ヘッダーとキャッシュヘッダーはモデルの入力にはなりません。

HTTP 上の意味が定義されている既知の入力は、パラメーターの位置に基づいて対応付けられるため、ドキュメント自体のフィールドは保持されます。自由形式の JSON ドキュメントでは body 引数を使用します。フィールドが宣言されているオブジェクトではフラットな引数を使用します。フラット化された filters フィールドが既存の仕様で省略されることと、FilterExpression スキーマへのフォールバックは、それぞれ別の制限事項です。この整理によって、フィルタースキーマのサポートが復元されることはありません。

最終的なツール名が重複している場合は、両方のルートを示して起動に失敗します。名前が重複する操作をマージするのではなく、v1 と v2 の仕様を個別に選択してください。

stderr に簡潔な操作名、レスポンスのステータス、所要時間を出力するには、ANYTYPE_MCP_DEBUG=1 を設定してください。引数、認証ヘッダー、ペイロード、操作テーブル全体は記録されません。

ツール定義の測定

bun run measure-tools
# Or inspect a different local OpenAPI document:
bun run measure-tools ./path/to/openapi.json

デフォルトのコマンドは、固定された v1 と v2 のフィクスチャを比較します。報告されるのはツール数、シリアル化された文字数、UTF-8 のバイト数であり、モデル固有のトークン数ではありません。

開発

ソースからのインストール

1. リポジトリをクローンします。

git clone https://github.com/anyproto/anytype-mcp.git
cd anytype-mcp

2. 依存関係をインストールします（Bun が必要です）。

bun install

3. プロジェクトをビルドします。

bun run build

4. パッケージをグローバルにリンクします（任意）。

bun link

貢献

Anytype を一緒に開発してくださることに感謝します！

❤️ このプロジェクトと関係者全員は、行動規範に従います。

🧑‍💻 質問の方法、イシューの作成方法、プルリクエストの提出方法については、貢献ガイドをご覧ください。

🫢 セキュリティ上の問題を発見した場合は、[email protected] までメールでご連絡ください。詳しくはセキュリティガイドをご覧ください。

🤝 Github をフォローし、貢献者コミュニティにご参加ください。

Any が制作 — スイスの協会 🇨🇭

MIT ライセンスの下で公開されています。