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：~/.cursor/mcp.json，Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json，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 文档。

传输方式

此服务支持三种 MCP 传输方式。STDIO 是默认方式，也是大多数桌面客户端（Claude Desktop、Cursor 等）使用的方式。对于远程客户端或 Web UI，可以使用旧版 SSE 传输方式或较新的 Streamable HTTP 传输方式，将其作为 HTTP 服务运行。

STDIO（默认）

TYPESENSE_API_KEY=xyz uv run python main.py

Streamable HTTP（推荐用于 Web 客户端）

/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/。设置 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 传输方式的无状态模式（某些 Web 客户端必需）
MCP_CORS_ORIGINS	(空)	以逗号分隔的允许来源。留空则禁用 CORS。* = 任意来源。

可用工具

Typesense MCP 服务提供以下工具：

服务管理

• check_typesense_health - 检查已配置的 Typesense 服务的健康状态
• list_collections - 获取 Typesense 服务中所有集合的列表

集合管理

• describe_collection - 获取特定集合的架构和元数据
• export_collection - 导出特定集合中的所有文档
• create_collection - 使用提供的架构创建新集合
• delete_collection - 删除特定集合
• truncate_collection - 删除集合中的所有文档，但保留架构

文档操作

• create_document - 在特定集合中创建单个新文档
• upsert_document - 在特定集合中插入或更新单个文档
• index_multiple_documents - 批量索引多个文档（创建、插入或更新）
• delete_document - 根据文档 ID 删除特定集合中的单个文档
• import_documents_from_csv - 将 CSV 数据中的文档导入集合

搜索功能

• search - 在特定集合中执行关键词搜索
• vector_search - 在特定集合中执行向量相似度搜索