typesense

This MCP server provides a bridge to a Typesense search index deployment, exposing a set of tools that allow you to manage collections, documents, and perform searches. After starting the server with uv, you can invoke commands to check health, list and manage collections, and perform document operations such as creating, updating, or deleting items, as well as bulk import and various search capabilities. The server is designed to work with a configured Typesense instance, using environment variables to connect (host, port, protocol, and API key). Use the available tools to scaffold and maintain your Typesense schemas and data programmatically.

Prerequisites:

• Python 3.x installed
• uv (the Python microservice runner) installed
• Git installed

1. Install uv locally (if not already installed)

   • macOS (via Homebrew): brew install uv
   • Linux: follow the installation guide at https://docs.astral.sh/uv/getting-started/installation/

2. Clone the MCP server repository git clone git@github.com:avarant/typesense-mcp-server.git ~/typesense-mcp-server

3. Install any Python dependencies if required by the server (check requirements.txt or setup instructions in the repo)

4. Configure environment variables (see mcp.json snippet in the repo and the next step):

   • TYPESENSE_HOST: Hostname or IP of the Typesense server
   • TYPESENSE_PORT: Port number (e.g., 8108)
   • TYPESENSE_PROTOCOL: http or https
   • TYPESENSE_API_KEY: Your Typesense API key

5. Run the MCP server using uv (as shown in the example configuration): uv --directory ~/typesense-mcp-server run mcp run main.py

6. (Optional) If you want to enable automatic installation via Smithery, run: npx -y @smithery/cli install @avarant/typesense-mcp-server --client claude

7. Verify the server is running by invoking one of the available tools (health, list_collections, etc.).

Notes and tips:

• Ensure your Typesense host, port, protocol, and API key are correctly set in the environment variables before starting the server.
• The server exposes a comprehensive set of tools for server management, collection management, document operations, and search capabilities. Use the tool names exactly as described in the README when issuing commands.
• If you encounter connectivity or authentication errors, double-check network access to the Typesense instance and verify that the API key has the required permissions.
• When updating collection schemas or documents, consider running small batches first to validate fields and mappings before large imports.
• The configuration shown uses uv to run a Python-based MCP server from a local directory. If you deploy to a different environment, adjust the directory and file paths accordingly.