Typesense MCP Server

Servidor MCP Typesense

Um servidor Model Context Protocol (MCP) que faz interface com Typesense

Instalação

Instale o uv

Requer Python 3.11 ou superior.

No Mac, você pode instalá-lo usando homebrew

brew install uv

Clone o pacote

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

Adicione o servidor à configuração do seu cliente MCP. A maioria dos clientes (Cursor em ~/.cursor/mcp.json, Claude Desktop em ~/Library/Application Support/Claude/claude_desktop_config.json, Windsurf, Zed, VS Code, etc.) aceita o mesmo formato 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": ""
      }
    }
  }
}

Consulte a documentação MCP do seu cliente para saber a localização exata do arquivo de configuração.

Transportes

O servidor suporta três transportes MCP. STDIO é o padrão e é o que a maioria dos clientes desktop (Claude Desktop, Cursor, etc.) utiliza. Para clientes remotos ou interfaces web, você pode executá-lo como um servidor HTTP usando o transporte SSE legado ou o novo transporte Streamable HTTP.

STDIO (padrão)

TYPESENSE_API_KEY=xyz uv run python main.py

Streamable HTTP (recomendado para clientes web)

Endpoint único em /mcp. Funciona com clientes baseados em navegador, como o chat web llama.cpp. Defina MCP_TRANSPORT=streamable-http (ou passe --http):

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

• O modo sem estado (MCP_STATELESS_HTTP=true) é necessário para clientes que não mantêm uma sessão MCP entre requisições.
• O CORS deve estar habilitado (MCP_CORS_ORIGINS) para clientes de navegador. Use uma origem específica como http://localhost:8080 em produção, em vez de *.

SSE (legado)

Dois endpoints, GET /sse para o fluxo de eventos e POST /messages/ para JSON-RPC. Defina MCP_TRANSPORT=sse (ou passe --sse):

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

Configuração

Variável de ambiente	Padrão	Descrição
MCP_TRANSPORT	stdio	stdio, sse ou streamable-http
MCP_HOST	0.0.0.0	Endereço de vinculação para transportes HTTP
MCP_PORT	8000	Porta de vinculação para transportes HTTP
MCP_STATELESS_HTTP	false	Modo sem estado para transportes HTTP (necessário para alguns clientes web)
MCP_CORS_ORIGINS	(vazio)	Origens permitidas separadas por vírgula. Vazio desabilita o CORS. * = qualquer.

Ferramentas Disponíveis

O Servidor MCP Typesense fornece as seguintes ferramentas:

Gerenciamento do Servidor

• check_typesense_health - Verifica o status de saúde do servidor Typesense configurado
• list_collections - Recupera uma lista de todas as coleções no servidor Typesense

Gerenciamento de Coleções

• describe_collection - Recupera o esquema e os metadados de uma coleção específica
• export_collection - Exporta todos os documentos de uma coleção específica
• create_collection - Cria uma nova coleção com o esquema fornecido
• delete_collection - Exclui uma coleção específica
• truncate_collection - Trunca uma coleção excluindo todos os documentos, mas mantendo o esquema

Operações de Documentos

• create_document - Cria um único novo documento em uma coleção específica
• upsert_document - Faz upsert (cria ou atualiza) um único documento em uma coleção específica
• index_multiple_documents - Indexa (cria, faz upsert ou atualiza) vários documentos em lote
• delete_document - Exclui um único documento pelo seu ID de uma coleção específica
• import_documents_from_csv - Importa documentos de dados CSV para uma coleção

Recursos de Busca

• search - Realiza uma busca por palavras-chave em uma coleção específica
• vector_search - Realiza uma busca por similaridade vetorial em uma coleção específica