Typesense MCP Server

Typesense MCP サーバー

Typesense と連携する Model Context Protocol（MCP）サーバーです。

インストール

uvをインストールします。

Python 3.11 以降が必要です。

Mac では、homebrewを使ってインストールできます。

brew install uv

パッケージをクローンします。

git clone [email protected]:avarant/typesense-mcp-server.git ~/typesense-mcp-server

サーバーを MCP クライアントの設定に追加します。ほとんどのクライアント（~/.cursor/mcp.json の Cursor、~/Library/Application Support/Claude/claude_desktop_config.json の Claude Desktop、Windsurf、Zed、VS Code など）は、同じ mcpServers 形式に対応しています。

{
  "mcpServers": {
    "typesense": {
      "command": "uv",
      "args": ["--directory", "~/typesense-mcp-server", "run", "mcp", "run", "main.py"],
      "env": {
        "TYPESENSE_HOST": "",
        "TYPESENSE_PORT": "",
        "TYPESENSE_PROTOCOL": "",
        "TYPESENSE_API_KEY": ""
      }
    }
  }
}

設定ファイルの正確な場所については、お使いのクライアントの MCP ドキュメントを参照してください。

トランスポート

このサーバーは 3 種類の MCP トランスポートに対応しています。STDIO がデフォルトで、ほとんどのデスクトップクライアント（Claude Desktop、Cursor など）で使用されています。リモートクライアントやウェブ UI では、従来の SSE トランスポートまたは新しい Streamable HTTP トランスポートを使って、HTTP サーバーとして実行できます。

STDIO（デフォルト）

TYPESENSE_API_KEY=xyz uv run python main.py

Streamable HTTP（ウェブクライアントに推奨）

/mcp の単一エンドポイントを使用します。llama.cpp のウェブチャットのようなブラウザベースのクライアントで動作します。MCP_TRANSPORT=streamable-http を設定するか、--http を渡します。

TYPESENSE_API_KEY=xyz \
MCP_TRANSPORT=streamable-http \
MCP_STATELESS_HTTP=true \
MCP_CORS_ORIGINS='*' \
uv run python main.py

• リクエストをまたいで MCP セッションを維持しないクライアントには、ステートレスモード（MCP_STATELESS_HTTP=true）が必要です。
• ブラウザクライアントでは CORS を有効にする必要があります（MCP_CORS_ORIGINS）。本番環境では * ではなく、http://localhost:8080 のように特定のオリジンを指定してください。

SSE（従来方式）

イベントストリーム用の GET /sse と、JSON-RPC 用の POST /messages/ の 2 つのエンドポイントがあります。MCP_TRANSPORT=sse を設定するか、--sse を渡します。

TYPESENSE_API_KEY=xyz MCP_TRANSPORT=sse uv run python main.py

設定

環境変数	デフォルト	説明
MCP_TRANSPORT	stdio	stdio、sse、または streamable-http
MCP_HOST	0.0.0.0	HTTP トランスポートのバインドアドレス
MCP_PORT	8000	HTTP トランスポートのバインドポート
MCP_STATELESS_HTTP	false	HTTP トランスポートのステートレスモード（一部のウェブクライアントで必要）
MCP_CORS_ORIGINS	(empty)	許可するオリジンをカンマ区切りで指定します。空の場合は CORS が無効になります。* = すべて。

利用可能なツール

Typesense MCP サーバーでは、次のツールを利用できます。

サーバー管理

• check_typesense_health - 設定された Typesense サーバーのヘルスステータスを確認します
• list_collections - Typesense サーバー内のすべてのコレクションの一覧を取得します

コレクション管理

• describe_collection - 特定のコレクションのスキーマとメタデータを取得します
• export_collection - 特定のコレクションからすべてのドキュメントをエクスポートします
• create_collection - 指定されたスキーマで新しいコレクションを作成します
• delete_collection - 特定のコレクションを削除します
• truncate_collection - スキーマを保持したまま、すべてのドキュメントを削除してコレクションを空にします

ドキュメント操作

• create_document - 特定のコレクションに新しいドキュメントを 1 つ作成します
• upsert_document - 特定のコレクションにドキュメントを 1 つアップサート（作成または更新）します
• index_multiple_documents - 複数のドキュメントを一括でインデックス化（作成、アップサート、または更新）します
• delete_document - 特定のコレクションから ID を指定してドキュメントを 1 つ削除します
• import_documents_from_csv - CSV データからコレクションにドキュメントをインポートします

検索機能

• search - 特定のコレクションでキーワード検索を実行します
• vector_search - 特定のコレクションでベクトル類似度検索を実行します