Searchcraft MCP Server: Vertical Search Toolkit for NL Command Ops

Searchcraft MCP Server

The Searchcraft MCP Server is a toolset based on the Searchcraft vertical search engine, used to manage documents, indexes, federations, access keys, and analytical data, and supports performing management operations through natural language instructions.

Search tools Developer tools #Search management #Document indexing #Key control #Data analysis .TypeScript

rating : 2.5 points

downloads : 1

update time : 2025-07-23

What is searchcraft-mcp-server?

searchcraft-mcp-server is an MCP server based on Searchcraft, providing a set of tools to manage documents, indexes, federations, access keys, and analytics in your Searchcraft cluster. It allows MCP clients (such as Claude Desktop) to perform management operations through natural language prompts.

How to use searchcraft-mcp-server?

To use searchcraft-mcp-server, you need to run the server locally and connect it to an MCP client such as Claude Desktop. By configuring environment variables and starting the server, you can utilize its various functions for index management, document operations, and access key control.

Applicable scenarios

This server is suitable for developers, data engineers, and system administrators who need to manage Searchcraft clusters. It can be used for tasks such as setting up search indexes, adding documents, viewing analytics, deleting documents, and managing access keys.

Main features

Index managementSupports creating, deleting, updating, and querying indexes, including obtaining index schemas and statistical information.

Document managementAllows adding, deleting, querying, and updating documents, and supports deleting documents by ID or field.

Federation managementProvides functions for creating, updating, and deleting federations, and supports viewing detailed federation information and statistical data.

Authentication and key managementCan create, delete, and update access keys, and supports filtering keys by organization, application, or federation.

Stop word and synonym managementAllows adding, deleting, and viewing stop words and synonyms in the index.

Search and measurementSupports executing search queries, obtaining measurement conversions, and summary data.

Advantages and limitations

Advantages

Provides an intuitive API interface for easy integration into other applications.

Supports multiple management operations, simplifying the maintenance of Searchcraft clusters.

Is compatible with MCP clients such as Claude Desktop, enhancing the user experience.

Limitations

Requires a certain technical background to configure and run the server.

Some commands and parameters may be difficult for non-technical personnel to understand.

Depends on the availability of the Searchcraft cluster; if the cluster is unavailable, operations cannot be performed.

How to use

Configure environment variables

Create a file named.env in the project root directory and fill in the following content:

Install dependencies

Use yarn to install project dependencies:

Build and start the server

Build and start the server:

Connect Claude Desktop

Add the MCP server configuration to the Claude Desktop configuration file:

Usage examples

Create an indexCreate an index for new search requirements and define its schema.

Add documentsAdd a batch of documents to an existing index for subsequent searches.

Delete a documentDelete a specific document from the index to clean up outdated or invalid data.

Frequently Asked Questions

What environment do I need to run searchcraft-mcp-server?

How can I ensure that Claude Desktop is correctly connected to the server?

How can I debug if I encounter an error?

Related resources

Searchcraft documentation

Official Searchcraft documentation, containing descriptions of all APIs and functions.

Vektron dashboard

Searchcraft's management dashboard for monitoring and managing clusters.

Searchcraft Discord

Searchcraft community support and discussion platform.

Searchcraft Reddit

Discussion and news section related to Searchcraft.

Searchcraft SDK

Searchcraft's React SDK for front - end integration.

🚀 searchcraft-mcp-server

An MCP Server powered by Searchcraft – the developer-first vertical search engine, providing tools for managing Searchcraft cluster resources.

🚀 Quick Start

Environment Variables

Create a .env file at the project's root and fill in the values:

# Server Config
USER_AGENT=searchcraft-mcp-server/<project-version>
DEBUG=true
PORT=3100

# Searchcraft Config
ENDPOINT_URL= # The endpoint url of your Searchcraft Cluster
ADMIN_KEY= # The admin key (super user key) of your Searchcraft Cluster

.env sample

Running the Server

Make sure your environment has the correct version of Node selected.

nvm use

Install dependencies with Yarn

yarn

Build & Start the server

yarn build
yarn start

✨ Features

Available Tools

Index Management

Tool Name	Description
create_index	Create a new index with the specified schema. This will empty the index if it already exists.
delete_index	Delete an index and all its documents permanently.
get_all_index_stats	Get document counts and statistics for all indexes.
get_index_schema	Get the schema definition for a specific index.
get_index_stats	Get statistics and metadata for a specific index (document count, etc.).
list_all_indexes	Get a list of all indexes in the Searchcraft instance.
patch_index	Make partial configuration changes to an index schema (search_fields, weight_multipliers, etc.).
update_index	Replace the entire contents of an existing index with a new schema definition.

Document Management

Tool Name	Description
add_documents	Add one or multiple documents to an index. Documents should be provided as an array of JSON objects.
delete_all_documents	Delete all documents from an index. The index will continue to exist after all documents are deleted.
delete_document_by_id	Delete a single document from an index by its internal Searchcraft ID (_id).
delete_documents_by_field	Delete one or several documents from an index by field term match (e.g., {id: 'xyz'} or {title: 'foo'}).
delete_documents_by_query	Delete one or several documents from an index by query match.
get_document_by_id	Get a single document from an index by its internal Searchcraft ID (_id).

Federation Management

Tool Name	Description
create_federation	Create or update a federation with the specified configuration.
delete_federation	Delete a federation permanently.
get_federation_details	Get detailed information for a specific federation.
get_federation_stats	Get document counts per index for a federation as well as the total document count.
get_organization_federations	Get a list of all federations for a specific organization.
list_all_federations	Get a list of all federations in the Searchcraft instance.
update_federation	Replace the current federation entity with an updated one.

Authentication & Key Management

Tool Name	Description
create_key	Create a new authentication key with specified permissions and access controls.
delete_all_keys	Delete all authentication keys on the Searchcraft cluster. Use with extreme caution!
delete_key	Delete a specific authentication key permanently.
get_application_keys	Get a list of all authentication keys associated with a specific application.
get_federation_keys	Get a list of all authentication keys associated with a specific federation.
get_key_details	Get detailed information for a specific authentication key.
get_organization_keys	Get a list of all authentication keys associated with a specific organization.
list_all_keys	Get a list of all authentication keys on the Searchcraft cluster.
update_key	Update an existing authentication key with new configuration.

Stopwords Management

Tool Name	Description
add_stopwords	Add custom stopwords to an index. These are added on top of the default language-specific dictionary.
delete_all_stopwords	Delete all custom stopwords from an index. This only affects custom stopwords, not the default language dictionary.
delete_stopwords	Delete specific custom stopwords from an index. This only affects custom stopwords, not the default language dictionary.
get_index_stopwords	Get all stopwords for an index, including both default language dictionary and custom stopwords.

Synonyms Management

Tool Name	Description
add_synonyms	Add synonyms to an index. Synonyms only work with fuzzy queries, not exact match queries.
delete_all_synonyms	Delete all synonyms from an index.
delete_synonyms	Delete specific synonyms from an index by their keys.
get_index_synonyms	Get all synonyms defined for an index.

Search & Measurement

Tool Name	Description
get_measure_conversion	Get measurement conversion data with optional filtering and aggregation parameters.
get_measure_summary	Get measurement summary data with optional filtering and aggregation parameters.
get_search_results	Performs a search query using the Searchcraft API with support for fuzzy/exact matching, facets, and date ranges.
get_searchcraft_status	Get the current status of the Searchcraft search service.

💻 Usage Examples

Usage With Claude Desktop

The server must be running in order for Claude Desktop to detect searchcraft-mcp-server's tools.

searchcraft-mcp-server uses StreamableHTTPServerTransport, so in order to connect it to Claude Desktop, we use mcp-remote ↗︎.

In your claude desktop config file, add the following:

claude_desktop_config.json

{
  "mcpServers": {
    "searchcraft": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:<MY-PORT-FROM-ENV>/mcp"
      ]
    }
  }
}

The claude desktop config file can be found at /Users/[My Workspace]]/Library/Application Support/Claude/claude_desktop_config.json. If no file exists here you can create it.

Claude desktop config example

Claude Desktop Node Version

⚠️ Important Note

We have experienced that when Claude Desktop runs the command to connect to the MCP server, it can sometimes choose an older version of Node. If older versions of node are installed on your system, this can lead to issues. Ensure that your default Node version on your system is high enough to properly run the server.