MCP Local Search

A Model Context Protocol (MCP) server that provides vector search capabilities over local files. This project enables semantic search across your local documents using modern embedding techniques, all running locally on your machine.

Features

• 🔍 Semantic search over local documents
• 📄 Support for PDF, text, and other document formats
• 🧠 Local embedding generation using transformers.js
• 🔒 Fully local operation - no data leaves your machine
• 🚀 Easy installation via npm or bun
• 🔌 MCP protocol implementation for integration with AI assistants

Installation

Using npm

npm install -g mcp-local-search

Using bun

bun install -g mcp-local-search

Usage

Starting the MCP Server

mcp-local-search start

Options:

• -p, --port <port> - Port to run the server on (default: 3000)
• -d, --data-dir <path> - Directory to store data (default: ./.mcp-local-search)

Indexing Files

mcp-local-search index <path>

Index a file or directory:

• <path> - Path to file or directory to index
• -c, --chunk-size <size> - Size of text chunks (default: 1000)
• -o, --chunk-overlap <size> - Overlap between chunks (default: 200)

Searching

mcp-local-search search "your search query"

Options:

• -l, --limit <number> - Maximum number of results (default: 5)
• -s, --min-score <number> - Minimum similarity score (default: 0.3)

Clearing the Index

mcp-local-search clear

Programmatic Usage

You can also use MCP Local Search as a library in your Node.js applications:

import { MCPServer } from 'mcp-local-search';

const server = new MCPServer({
  port: 3000,
  dataDir: './data'
});

await server.initialize();
await server.start();

// Later, to stop the server
await server.stop();

MCP Protocol

This server implements the Model Context Protocol, allowing it to be used with compatible AI assistants. The WebSocket endpoint is available at ws://localhost:3000/mcp when the server is running.

Supported methods:

• index_file - Index a file
• search - Search the vector store
• clear_index - Clear the index
• get_stats - Get statistics about the index

Development

Setup

# Clone the repository
git clone https://github.com/windsurf/mcp-local-search.git
cd mcp-local-search

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Testing

npm test

License

MIT