Typesense MCP Server

What is Typesense MCP Server about?

Provides a Model Context Protocol (MCP) server that exposes Typesense collections as resources and tools, allowing large language models (LLMs) to list collections, retrieve documents, run searches, and obtain collection statistics.

How to use Typesense MCP Server?

1. Install – globally with npm install -g typesense-mcp-server or locally with npm install typesense-mcp-server.
2. Run – start the server via Node or via an MCP client (e.g., Claude Desktop) using an npx command that points to the package and supplies connection arguments (--host, --port, --protocol, --api-key).
3. Configure – add the server entry to the mcpServers section of the client’s configuration file, referencing the command and arguments.
4. Interact – use the provided tools (typesense_query, typesense_get_document, typesense_collection_stats) and prompts (analyze_collection, search_suggestions) from within the LLM environment.

Key Features of Typesense MCP Server

• Resources: List collections via typesense:// URIs with JSON schema metadata.
• Tools:
  • typesense_query – full‑text search with filtering, sorting, and limiting.
  • typesense_get_document – fetch a document by its ID.
  • typesense_collection_stats – retrieve collection statistics and schema.
• Prompts:
  • analyze_collection – insight into schema and data distribution.
  • search_suggestions – recommendations for effective query construction.
• Templates: Ready‑made request templates for search and collection inspection.
• Logging: Detailed logs written to /tmp/typesense-mcp.log for troubleshooting.

Use Cases of Typesense MCP Server

• Semantic Search for LLMs – let a model browse a product catalog stored in Typesense and return relevant items.
• Data Exploration – enable agents to analyze collection structures and generate summary reports.
• Chat‑Powered Retrieval Augmented Generation (RAG) – fetch specific documents or snippets during a conversation.
• Automated QA – use search_suggestions to craft optimal queries for a given dataset.

FAQ from the Typesense MCP Server

• Do I need a Typesense server beforehand? Yes, you must have a running Typesense instance and provide its host, port, protocol, and API key.
• Can I run the server locally for development? Absolutely – clone the repo, run npm install, then npm run build and start with node dist/index.js ….
• How do I debug interactions? Use the MCP Inspector (npm run inspector) which exposes a web UI for tracing stdio communication.
• What logging information is available? All requests, responses, and errors are written to /tmp/typesense-mcp.log.
• Is the package compatible with other MCP clients? Yes, any client that follows the Model Context Protocol can communicate with this server via stdio.

Typesense MCP Server

---

A Model Context Protocol (MCP) server implementation that provides AI models with access to Typesense search capabilities. This server enables LLMs to discover, search, and analyze data stored in Typesense collections.

Demo

Features

Resources

• List and access collections via typesense:// URIs
• Each collection has a name, description, and document count
• JSON mime type for schema access

Tools

• typesense_query

  • Search for documents in Typesense collections with powerful filtering
  • Input: Query text, collection name, search fields, filters, sort options, limit
  • Returns matching documents with relevance scores

• typesense_get_document

  • Retrieve specific documents by ID from collections
  • Input: Collection name, document ID
  • Returns complete document data

• typesense_collection_stats

  • Get statistics about a Typesense collection
  • Input: Collection name
  • Returns collection metadata, document count, and schema information

Prompts

• analyze_collection

  • Analyze collection structure and contents
  • Input: Collection name
  • Output: Insights about schema, data types, and statistics

• search_suggestions

  • Get suggestions for effective search queries for a collection
  • Input: Collection name
  • Output: Recommended search strategies based on collection schema

Installation

Via npm

# Global installation
npm install -g typesense-mcp-server

# Local installation
npm install typesense-mcp-server

Via mcp-get

npx @michaellatman/mcp-get@latest install typesense-mcp-server

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Installation for Development

Using Claude Desktop

To use with Claude Desktop, add the server config:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "typesense": {
      "command": "node",
      "args": [
        "~/typesense-mcp-server/dist/index.js",
        "--host", "your-typesense-host",
        "--port", "8108",
        "--protocol", "http",
        "--api-key", "your-api-key"
      ]
    },
  }
}

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Components

Resources

The server provides information about Typesense collections:

• Collection Schemas (typesense://collections/<collection>)
  • JSON schema information for each collection
  • Includes field names and data types
  • Sample documents for understanding data structure

Resource Templates

The server provides templates for:

• typesense_search - Template for constructing Typesense search queries
• typesense_collection - Template for viewing Typesense collection details

Usage with Claude Desktop

To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your claude_desktop_config.json:

{
  "mcpServers": {
    "typesense": {
      "command": "npx",
      "args": [
        "-y",
        "typesense-mcp-server",
        "--host", "your-typesense-host",
        "--port", "8108",
        "--protocol", "http",
        "--api-key", "your-api-key"
      ]
    }
  }
}

Logging

The server logs information to a file located at:

/tmp/typesense-mcp.log

This log contains detailed information about server operations, requests, and any errors that occur.

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.