Typesense MCP server
Commit Nov 12, 2026Enables AI clients to manage collections, perform keyword and vector searches, and manipulate documents within a Typesense search engine.
Also known as avarant/typesense-mcp-server
- Stars
- 10
- Tools
- 14
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- MIT
What is Typesense MCP?
Typesense enables AI clients to manage collections, perform keyword and vector searches, and manipulate documents within a Typesense search engine. It exposes 14 tools, such as check_typesense_health, list_collections, describe_collection.
Summary generated from the project's README
About Typesense MCP server
Managing search engines and data collections through an AI interface is what this server enables for developers using Typesense. It allows AI clients to interact directly with your search engine to perform keyword searches, execute vector similarity searches, and manipulate documents. You can use it locally with desktop clients like Claude Desktop or Cursor via STDIO, or deploy it as a remote service using SSE or Streamable HTTP transports for web-based interfaces.
Setup requires Python 3.11 or higher and the uv package manager. To connect, you must provide environment variables including your Typesense host, port, protocol, and API key. The server includes security features for remote access, such as host and origin checks, bearer tokens, and CORS configuration. It provides a comprehensive suite of tools for server health checks, collection schema management, document upserting, and batch indexing from CSV data.
What you can do with it
- 1Perform similarity searchesAsk your AI client to find items in a collection using vector similarity.
- 2Manage search schemasInstruct the AI to create, describe, or delete specific data collections.
- 3Bulk import dataHave the AI assistant ingest multiple records from a CSV file into your index.
- 4Monitor engine statusVerify if your Typesense instance is running correctly using a health check tool.
Written from the project's README. Every use case is checked against a quote from it.
Typesense MCP tools 14
Detected from the READMEcheck_typesense_healthlist_collectionsdescribe_collectionexport_collectioncreate_collectiondelete_collectiontruncate_collectioncreate_documentupsert_documentindex_multiple_documentsdelete_documentimport_documents_from_csv
Show all 14 toolsShow fewer tools
searchvector_search
Configuration
MCP_ALLOWED_HOSTSMCP_AUTH_TOKENMCP_CORS_ORIGINSMCP_HOSTMCP_STATELESS_HTTPMCP_TRANSPORTTYPESENSE_API_KEYTYPESENSE_HOSTTYPESENSE_PORTTYPESENSE_PROTOCOL
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableavarant/typesense-mcp-server is public and reachablegithub.com/avarant/typesense-mcp-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/avarant/typesense-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model14 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubTypesense 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 git@github.com: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 likehttp://localhost:8080in production rather than*.
HTTP security
The HTTP transports give full access to your Typesense instance using the configured API key, so they are locked down by default:
- Loopback only. The server listens on
127.0.0.1unless you setMCP_HOST. - Host/Origin checks. Requests must address the server as
localhost,127.0.0.1or[::1](plus anything inMCP_ALLOWED_HOSTS), and browser requests must come from a localhost page or an origin listed inMCP_CORS_ORIGINS. This blocks DNS-rebinding attacks from websites you visit. WithMCP_CORS_ORIGINS='*', only localhost pages are allowed. - Token required for remote access. To accept connections from other machines, set
MCP_HOST=0.0.0.0,MCP_AUTH_TOKEN, andMCP_ALLOWED_HOSTSto the hostname/IP clients use. Clients must then sendAuthorization: Bearer <token>. The server refuses to start on a non-loopback address without a token unlessMCP_ALLOW_UNAUTHENTICATED=true(only for setups that enforce auth elsewhere, e.g. a reverse proxy).
TYPESENSE_API_KEY=xyz \
MCP_TRANSPORT=streamable-http \
MCP_HOST=0.0.0.0 \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
MCP_ALLOWED_HOSTS=mcp.example.com \
uv run python main.py
When running the HTTP transport in Docker, set MCP_HOST=0.0.0.0 inside the container (plus a token), since connections from the host aren't loopback from the container's point of view.
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
| Env var | Default | Description |
|---|---|---|
MCP_TRANSPORT |
stdio |
stdio, sse, or streamable-http |
MCP_HOST |
127.0.0.1 |
Bind address for HTTP transports |
MCP_PORT |
8000 |
Bind port for HTTP transports |
MCP_AUTH_TOKEN |
(empty) | Bearer token required on HTTP requests. Required when MCP_HOST is not loopback. |
MCP_ALLOWED_HOSTS |
(empty) | Extra accepted Host values, comma-separated (localhost is always allowed). No port = any port. |
MCP_ALLOW_UNAUTHENTICATED |
false |
Allow a non-loopback MCP_HOST without MCP_AUTH_TOKEN (auth enforced elsewhere). |
MCP_STATELESS_HTTP |
false |
Stateless mode for HTTP transports (required for some web clients) |
MCP_CORS_ORIGINS |
(empty) | Comma-separated allowed origins. Empty disables CORS. * = any. |
CSV_IMPORT_DIR |
(empty) | Directory import_documents_from_csv may read files from. Empty disables file-path imports (inline CSV only). |
Available Tools
The Typesense MCP Server provides the following tools:
Server Management
check_typesense_health- Checks the health status of the configured Typesense serverlist_collections- Retrieves a list of all collections in the Typesense server
Collection Management
describe_collection- Retrieves the schema and metadata for a specific collectionexport_collection- Exports all documents from a specific collectioncreate_collection- Creates a new collection with the provided schemadelete_collection- Deletes a specific collectiontruncate_collection- Truncates a collection by deleting all documents but keeping the schema
Document Operations
create_document- Creates a single new document in a specific collectionupsert_document- Upserts (creates or updates) a single document in a specific collectionindex_multiple_documents- Indexes (creates, upserts, or updates) multiple documents in a batchdelete_document- Deletes a single document by its ID from a specific collectionimport_documents_from_csv- Imports documents from inline CSV data, or from a CSV file insideCSV_IMPORT_DIR, into a collection
Search Capabilities
search- Performs a keyword search on a specific collectionvector_search- Performs a vector similarity search on a specific collection
Typesense MCP questions
What tools does Typesense MCP provide?
It exposes 14 tools, including check_typesense_health, list_collections, describe_collection, export_collection, create_collection.
What transport methods does the server support?
The server supports STDIO (default), SSE (legacy), and Streamable HTTP (recommended for web clients).
How can I perform a similarity search?
You can use the vector_search tool to perform vector similarity searches on a specific collection.
Is there a way to import data from CSV files?
Yes, the import_documents_from_csv tool allows you to import documents from inline CSV data or from files located in the CSV_IMPORT_DIR directory.
How is security handled for HTTP transports?
HTTP transports are locked down by default, listening on loopback only and requiring host/origin checks. For remote access, you must set an MCP_AUTH_TOKEN.