Typesense MCP Server

A Model Context Protocol (MCP) Server that interfaces with Typesense

Installation

Install uv

Requires Python 3.11 or higher.

On Mac you can install it using homebrew

brew install uv

Clone the package

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

Add the server to your MCP client config. Most clients (Cursor at ~/.cursor/mcp.json, Claude Desktop at ~/Library/Application Support/Claude/claude_desktop_config.json, Windsurf, Zed, VS Code, etc.) accept the same mcpServers shape:

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

Refer to your client’s MCP documentation for the exact config file location.

Transports

The server supports three MCP transports. STDIO is the default and is what most desktop clients (Claude Desktop, Cursor, etc.) use. For remote clients or web UIs, you can run it as an HTTP server using either the legacy SSE transport or the newer Streamable HTTP transport.

STDIO (default)

TYPESENSE_API_KEY=xyz uv run python main.py

Streamable HTTP (recommended for web clients)

Single endpoint at /mcp. Works with browser-based clients like the llama.cpp web chat. Set MCP_TRANSPORT=streamable-http (or pass --http):

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

• Stateless mode (MCP_STATELESS_HTTP=true) is required for clients that don’t keep an MCP session across requests.
• CORS must be enabled (MCP_CORS_ORIGINS) for browser clients. Use a specific origin like http://localhost:8080 in production rather than *.

SSE (legacy)

Two endpoints, GET /sse for the event stream and POST /messages/ for JSON-RPC. Set MCP_TRANSPORT=sse (or pass --sse):

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

Configuration