check_typesense_healthLABSCO SUMMARY
Enough of Typesense to build an index and query it in the same conversation.
The set covers both halves that usually live in separate tools: you can define a collection, push documents into it from a batch or a CSV, and then immediately search it by keyword or by vector without switching to a client library. Three transports is more than most servers of this size offer, and the reason shows in the configuration — stateless mode and an explicit CORS origin exist so a browser-based chat client can talk to it directly.
What it is
A Python client for a Typesense node covering the whole loop: collection lifecycle, document writes, both search modes, and a health check. It speaks stdio for desktop clients and Streamable HTTP or SSE for browser-based ones.
What you get
- Search two ways against a collection — keyword search, and vector similarity search (search, vector_search).
- Collections listed, described with their schema and metadata, created from a schema you supply, and deleted (list_collections, describe_collection, create_collection, delete_collection).
- A collection emptied of documents while its schema stays in place, and a full export of everything in one (truncate_collection, export_collection).
- Documents written one at a time, created outright or upserted when the record may already exist, and deleted by ID (create_document, upsert_document, delete_document).
- Bulk loading two ways: a batch of documents created, upserted or updated in one call, and documents imported straight from CSV data (index_multiple_documents, import_documents_from_csv).
- A health check on the configured node, for when it is not obvious whether the query or the server is the problem (check_typesense_health).
Requirements
Python 3.11 or higher and uv, plus a clone of the repository — it runs as uv --directory <path> run mcp run main.py rather than from a published package. Four values carry the connection: TYPESENSE_HOST, TYPESENSE_PORT, TYPESENSE_PROTOCOL and TYPESENSE_API_KEY. Stdio is the default; for a browser client set MCP_TRANSPORT to streamable-http, which serves a single /mcp endpoint, and turn on MCP_STATELESS_HTTP for clients that do not keep a session across requests. CORS is off until MCP_CORS_ORIGINS names an origin — name the real one rather than leaving a wildcard in production.
Setup effort
Build from source — clone the repository, then follow the project's own run instructions
USE CASES
01
Standing up a new search index
Define the collection from a schema, load the first batch of documents, then query it to see whether the schema was right.
02
Getting a spreadsheet of records into search
Import the CSV directly rather than writing a conversion script first.
03
Finding out why a query returns nothing
Check the node is healthy, read the collection's actual schema, then look at what is really in it.
04
Testing semantic retrieval against your own data
Run vector similarity search on the collection and compare it with the keyword result on the same query.
05
Reloading a collection from scratch
Empty it without losing the schema, then push the fresh documents in.
14 tools
Listed in project docs. Your client may show a different list.
list_collectionsdescribe_collectionexport_collectioncreate_collectiondelete_collectiontruncate_collectioncreate_documentupsert_documentindex_multiple_documentsdelete_documentimport_documents_from_csvsearchvector_searchBEFORE YOU INSTALL
What to know first
Tools you get
14 tools named in the project's documentation.
Requires
- uv on PATH
- Python 3.11 or later
- A Typesense node to connect to — its TYPESENSE_HOST, TYPESENSE_PORT, TYPESENSE_PROTOCOL and TYPESENSE_API_KEY go in the client's env block
Where it runs
Both documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
git clone git@github.com:avarant/typesense-mcp-server.git ~/typesense-mcp-serverMCP Clients
Cursor, Claude Desktop
JSON
{
"mcpServers": {
"typesense": {
"command": "uv",
"args": [
"--directory",
"~/typesense-mcp-server",
"run",
"mcp",
"run",
"main.py"
],
"env": {
"TYPESENSE_HOST": "",
"TYPESENSE_PORT": "",
"TYPESENSE_PROTOCOL": "",
"TYPESENSE_API_KEY": ""
}
}
}
}The four values are your Typesense node's host, port, protocol and API key. The project's example leaves them empty, and the server cannot connect until they are set. If your client does not expand ~ in args, ~/typesense-mcp-server has to be the clone's full path.
