Typesense MCP Interface

---

An implementation adhering to the Model Context Protocol (MCP), specifically engineered to grant Large Language Models (LLMs) programmatic access to the high-performance search engine, Typesense. This system empowers agents to execute sophisticated discovery, retrieval, and statistical analysis on data resident within specified Typesense collections.

Demonstration

Core Capabilities

Accessible Data Sources (Resources)

• Enables listing and referencing of data containers via standardized typesense:// Uniform Resource Identifiers (URIs).
• Metadata provided for each container: a brief description and the total count of indexed records.
• Schema definitions are exposed using the JSON MIME type.

Defined Agent Tools

• typesense_query
• Executes complex document searches within designated Typesense indexes, supporting granular filtering logic.
• Inputs: The search term, target index identifier, fields to examine, conditional predicates, ordering parameters, and result count limits.

• Output: A list of relevant documents, each accompanied by a computed relevance metric.

• typesense_get_document

• Fetches the complete data payload for a single record identified by its unique key from a specified index.
• Inputs: Index name and the document's primary identifier.

• Output: The full document object.

• typesense_collection_stats

• Retrieves operational metrics and structural details pertaining to a Typesense index.
• Inputs: Index identifier.
• Output: Metadata summarizing the index, including document volume and field structure (schema).

Built-in Agent Prompts

• analyze_collection
• Generates high-level summaries concerning the organization and contents of an index.
• Input: Index identifier.

• Output: Interpretive findings regarding the schema, field classifications, and summary statistics.

• search_suggestions

• Proposes effective search strategies tailored for leveraging the structure of a specific index.
• Input: Index identifier.
• Output: Recommendations on optimal query construction based on the known schema.

Deployment Instructions

Via npm Package Manager

bash

For system-wide access

npm install -g typesense-mcp-server

For project-local integration

npm install typesense-mcp-server

Via mcp-get Utility

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

Development Environment Setup

Acquire dependencies: bash npm install

Compile the server artifact: bash npm run build

Enable continuous rebuilding during development: bash npm run watch

Configuration for Local Runtime (e.g., Claude Desktop)

For seamless integration with host applications like Claude Desktop, configure the server path and connection parameters in the designated configuration file:

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

Windows Path: %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 Utility

Debugging communication over standard I/O streams can be complex. We advocate using the specialized MCP Inspector, accessible via a package script:

bash npm run inspector

This command yields a local URL where browser-based inspection tools are hosted.

Structural Elements

Data Resource Endpoints

The server exposes introspection capabilities for Typesense indexes:

• Index Schemas (typesense://collections/<collection_name>)
• Delivers the JSON representation of the index structure.
• Details field names and their respective data types.
• Includes representative document samples for structural context.

Query Templates

The server offers pre-defined templates to guide complex interactions:

• typesense_search - Structure for formulating detailed Typesense search requests.
• typesense_collection - Template for querying and displaying index summary details.

Usage in Desktop Environment

To activate this connector within the Claude Desktop client, modify the "mcpServers" section of claude_desktop_config.json as follows, utilizing npx for execution:

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

Operational Logging

Diagnostic and operational data is persistently recorded to the following file path:

/tmp/typesense-mcp.log

This log file captures server initialization events, incoming requests, dispatched operations, and any encountered failures.

Licensing Information

This MCP adapter is distributed under the permissive MIT License. This grants users the freedom to employ, adapt, and redistribute the software, contingent upon adherence to the stipulated terms outlined in the accompanying LICENSE file within the repository.