Typesense MCP Server

Servidor MCP de Typesense

Un Model Context Protocol (MCP) Server que interactúa con Typesense

Instalación

Instala uv

Requiere Python 3.11 o superior.

En Mac puedes instalarlo usando homebrew

brew install uv

Clona el paquete

git clone git@github.com:avarant/typesense-mcp-server.git ~/typesense-mcp-server

Añade el servidor a la configuración de tu cliente MCP. La mayoría de los clientes (Cursor en ~/.cursor/mcp.json, Claude Desktop en ~/Library/Application Support/Claude/claude_desktop_config.json, Windsurf, Zed, VS Code, etc.) aceptan la misma forma de 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": ""
      }
    }
  }
}

Consulta la documentación MCP de tu cliente para conocer la ubicación exacta del archivo de configuración.

Transportes

El servidor soporta tres transportes MCP. STDIO es el predeterminado y es el que usan la mayoría de los clientes de escritorio (Claude Desktop, Cursor, etc.). Para clientes remotos o interfaces web, puedes ejecutarlo como servidor HTTP usando el transporte SSE heredado o el más reciente Streamable HTTP.

STDIO (predeterminado)

TYPESENSE_API_KEY=xyz uv run python main.py

Streamable HTTP (recomendado para clientes web)

Punto final único en /mcp. Funciona con clientes basados en navegador como el chat web llama.cpp. Establece MCP_TRANSPORT=streamable-http (o pasa --http):

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

• El modo sin estado (MCP_STATELESS_HTTP=true) es necesario para clientes que no mantienen una sesión MCP entre peticiones.
• CORS debe estar habilitado (MCP_CORS_ORIGINS) para clientes de navegador. Usa un origen específico como http://localhost:8080 en producción en lugar de *.

SSE (heredado)

Dos puntos finales, GET /sse para el flujo de eventos y POST /messages/ para JSON-RPC. Establece MCP_TRANSPORT=sse (o pasa --sse):

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

Configuración

Variable de entorno	Predeterminado	Descripción
MCP_TRANSPORT	stdio	stdio, sse o streamable-http
MCP_HOST	0.0.0.0	Dirección de enlace para transportes HTTP
MCP_PORT	8000	Puerto de enlace para transportes HTTP
MCP_STATELESS_HTTP	false	Modo sin estado para transportes HTTP (necesario para algunos clientes web)
MCP_CORS_ORIGINS	(vacío)	Orígenes permitidos separados por comas. Vacío deshabilita CORS. * = cualquier.

Herramientas disponibles

El servidor MCP de Typesense proporciona las siguientes herramientas:

Gestión del servidor

• check_typesense_health - Comprueba el estado de salud del servidor Typesense configurado
• list_collections - Recupera una lista de todas las colecciones del servidor Typesense

Gestión de colecciones

• describe_collection - Recupera el esquema y los metadatos de una colección específica
• export_collection - Exporta todos los documentos de una colección específica
• create_collection - Crea una nueva colección con el esquema proporcionado
• delete_collection - Elimina una colección específica
• truncate_collection - Trunca una colección eliminando todos los documentos pero conservando el esquema

Operaciones con documentos

• create_document - Crea un único documento nuevo en una colección específica
• upsert_document - Inserta o actualiza (upsert) un único documento en una colección específica
• index_multiple_documents - Indexa (crea, inserta o actualiza) varios documentos en un lote
• delete_document - Elimina un único documento por su ID de una colección específica
• import_documents_from_csv - Importa documentos desde datos CSV a una colección

Capacidades de búsqueda

• search - Realiza una búsqueda por palabras clave en una colección específica
• vector_search - Realiza una búsqueda de similitud vectorial en una colección específica