Typesense

What is mcp-typesense-server?

mcp-typesense-server is a Model Context Protocol (MCP) server that allows AI models, specifically Large Language Models (LLMs), to interact with Typesense, a fast, open-source search engine. It enables LLMs to discover, search, and analyze data stored in Typesense collections.

How to use mcp-typesense-server?

Installation

You can install mcp-typesense-server globally or locally via npm:

npm install -g typesense-mcp-server
npm install typesense-mcp-server

Alternatively, you can use mcp-get:

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

Integration with Claude Desktop

To use with Claude Desktop, you need to add a configuration to your claude_desktop_config.json file. For example:

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

For debugging, you can use the MCP Inspector by running:

npm run inspector

Key Features of mcp-typesense-server

Resources

• Collection Listing: List and access Typesense collections using typesense:// URIs.
• Collection Details: Each collection provides its name, description, and document count.
• Schema Access: JSON mime type for accessing collection schemas.

Tools

• typesense_query: Search for documents in Typesense collections with advanced filtering, sorting, and limiting options.
• typesense_get_document: Retrieve specific documents by their ID from collections.
• typesense_collection_stats: Get statistics about a Typesense collection, including metadata, document count, and schema information.

Prompts

• analyze_collection: Analyze the structure and content of a collection to gain insights into its schema and data types.
• search_suggestions: Get recommendations for effective search queries based on the collection's schema.

Components

• Collection Schemas: Provides JSON schema information for each collection, including field names, data types, and sample documents.
• Resource Templates: Includes templates for typesense_search (for constructing search queries) and typesense_collection (for viewing collection details).

Use Cases of mcp-typesense-server

• AI-powered Search: Enable LLMs to perform intelligent searches over large datasets stored in Typesense.
• Data Analysis by LLMs: Allow AI models to analyze and understand the structure and content of Typesense collections.
• Automated Data Retrieval: Facilitate automated retrieval of specific documents or statistics from Typesense by AI agents.
• Enhanced LLM Capabilities: Extend the capabilities of LLMs by providing them with real-time access to structured data.

FAQ about mcp-typesense-server

Q: What is the Model Context Protocol (MCP)? A: The Model Context Protocol (MCP) is a standard that allows AI models to interact with external tools and data sources. mcp-typesense-server is an implementation of this protocol for Typesense.

Q: What is Typesense? A: Typesense is a fast, open-source search engine that provides a robust solution for building search experiences.

Q: How does mcp-typesense-server help LLMs? A: It provides LLMs with the ability to discover, search, and analyze data within Typesense collections, enhancing their knowledge and analytical capabilities.

Q: Where can I find the logs for mcp-typesense-server? A: The server logs are located at /tmp/typesense-mcp.log.

Q: What license is mcp-typesense-server released under? A: It is licensed under the MIT License, allowing for free use, modification, and distribution.

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.