Overview

This MCP (Model Context Protocol) server integrates Typesense search into an LLM-friendly toolset so language models and agents can discover, search, and analyze Typesense-hosted data as context for generation tasks. It implements a lightweight HTTP layer that translates MCP tool calls into Typesense queries, returning ranked documents, facets, and metadata in a format that LLMs and orchestration frameworks can consume.

By exposing Typesense capabilities (keyword search, filtering, faceting and optional vector search) through MCP-compatible endpoints, the server makes it straightforward to build retrieval-augmented generation (RAG) systems, context-aware assistants, and analytics workflows that rely on fast, relevant document retrieval. The server is intended for developers who want to plug Typesense into LLM toolchains with minimal glue code.

Features

MCP-compatible tool surface for LLMs and agents
Keyword and filter-based search against Typesense collections
Faceting and aggregation support to surface structured context
Optional vector search integration where the Typesense collection includes vector fields
Paging and top-k retrieval configuration for precise context sizing
Lightweight deployment: runs locally, in Docker, or behind standard cloud services
Simple configuration via environment variables or .env files

Installation / Configuration

Prerequisites

Node.js (16+), or run via Docker
A running Typesense cluster (cloud-managed or self-hosted)
Typesense API key with read permissions for the target collections

Clone and run locally

git clone https://github.com/suhail-ak-s/mcp-typesense-server.git
cd mcp-typesense-server
npm install
# create a .env file (see example below)
npm start

Example .env

# Typesense connection
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz

# Server options
PORT=8080
DEFAULT_COLLECTION=documents
DEFAULT_TOP_K=5

Docker

docker run -p 8080:8080 \
  -e TYPESENSE_HOST=typesense.example.com \
  -e TYPESENSE_API_KEY=xyz \
  -e DEFAULT_COLLECTION=documents \
  ghcr.io/your-repo/mcp-typesense-server:latest

Configuration notes

DEFAULT_COLLECTION: fall-back Typesense collection used when requests omit a collection.
DEFAULT_TOP_K: number of results returned per query when not specified.
If your Typesense setup exposes vector fields, the server will accept requests requesting vector search against configured vector fields (requires corresponding Typesense collection configuration).

Available Tools / Resources

The server exposes a small set of HTTP endpoints that map to Typesense operations and MCP tool semantics.

Method	Path	Description
GET	/health	Basic health check for the MCP server
GET	/collections	List available Typesense collections
POST	/search	Execute a search (keyword/filter/top_k) and return ranked documents
POST	/vector_search	(Optional) Perform vector search if collection supports vector fields
POST	/facets	Run a search with facet aggregation
POST	/document	Fetch a single document by id

Example request formats (search)

Body: { “q”: “query string”, “collection”: “books”, “filters”: “author:John”, “top_k”: 5 }

Example response (simplified)

{
  "collection": "books",
  "results": [
    {"id":"123", "text":"...", "score": 12.4, "metadata": {"author":"Jane"}},
    {"id":"456", "text":"...", "score": 10.1, "metadata": {"author":"John"}}
  ],
  "total": 42
}

Use Cases

Retrieval-Augmented Generation (RAG)
- Use the /search endpoint to fetch top-k relevant passages and supply them as context to an LLM prompt for accurate, source-grounded answers.
- Example: query a product manual collection to answer user support questions with citations to matching sections.
Conversational Assistants with Context
- During multi-turn conversations, retrieve recent or relevant documents and include summaries in the system prompt to keep the assistant informed of user-specific data from Typesense.
Semantic and Hybrid Search
- If your Typesense collection holds vector embeddings, leverage /vector_search to perform semantic retrieval and combine results with keyword filters for hybrid relevance.
Analytics and Exploration
- Use /facets to produce aggregated counts (e.g., document counts per department or tag) so an LLM can reason over distributional insights or generate summaries of a corpus.
Chaining LLM Tools
- Expose the MCP server as a tool in an LLM agent framework. The agent can call search, analyze results, and then invoke other tools (summarizers, translators) to produce a multi-step workflow.

Example curl search

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"q":"installation error", "collection":"docs", "top_k":3}'

Next steps and tips

Secure the server behind authentication and TLS when exposing it to production systems.
Tune DEFAULT_TOP_K and prompt-engineering to balance context size vs. token cost.
If using vector search, ensure embeddings are computed consistently (same model and dimensionality) and stored in Typesense vector fields.
Integrate this MCP server as a tool in agent frameworks (LangChain, LlamaIndex, or custom orchestrators) to provide a searchable knowledge layer for LLM-driven applications.

Typesense MCP Server for LLM Search and Analysis