Local Search

You can run the Local Search MCP Server to perform semantic search over indexed documents using vector embeddings. It powers natural language queries across repositories and web pages, returning contextual results that help you find information faster.

How to use

Use an MCP client to connect to the Local Search MCP Server. You can run the server locally via a package runner or by starting a built JavaScript entry point, then configure your MCP client to target that local server. Once connected, you can search across indexed files, fetch repositories or individual files for indexing, monitor progress of long-running indexing tasks, and manage the job queue.

How to install

Prerequisites before you begin: install Node.js (version 18 or newer) and a package manager like npm or yarn. You may also want Git for development tasks.

# Install globally for quick local usage
npm install -g local-search-mcp

# Or run directly with npx (no installation needed)
npx local-search-mcp

Configuration

Configure how the MCP server runs and where it stores data and documents. The following environment variables customize storage locations.

{
  "mcpServers": {
    "local-search": {
      "command": "npx",
      "args": ["-y", "local-search-mcp"],
      "env": {
        "MCP_DATA_FOLDER": "/optional/custom/data/path",
        "MCP_DOCS_FOLDER": "/optional/custom/docs/path"
      }
    }
  }
}

Usage details

Two common ways to run the server are demonstrated here. Pick the one that matches how you prefer to deploy locally.

# Run via npx (no installation required)
npx -y local-search-mcp

# Or run as a locally built node script after cloning the source
node /absolute/path/to/local-search-mcp/build/index.js

Tools and capabilities

The server exposes a set of tools for indexing, search, and job management. You can perform semantic searches, fetch repositories or files for indexing, remove indexed files, flush the database, and monitor asynchronous jobs.

Security and maintenance notes

Keep your data and access controls up to date. Regularly review environment variables and ensure only trusted clients can initiate indexing jobs or retrieve results. Manage storage paths to avoid unbounded growth and consider archiving or purging old data as needed.

Troubleshooting

If indexing jobs stall or fail, check the job status endpoint for progress and error messages. Ensure your environment paths exist and have proper permissions. For long-running tasks, verify that network access, repository URLs, and file patterns are correct.

Development notes

If you contribute code, follow the standard development flow: install dependencies, build, and run in development mode as needed.

Available tools

search_documents

Perform AI-enhanced semantic search with content classification, domain detection, and intelligent recommendations.

get_file_details

Retrieve detailed content of a specific file with surrounding chunk context.

fetch_repo

Clone a Git repository, convert to markdown, and add to searchable index. Returns a job ID for progress tracking.

fetch_file

Download a single file from a URL and add it to the searchable index. Returns a job ID for progress tracking.

remove_file

Delete a file and all its associated chunks and embeddings from the index.

flush_all

Flush the entire database and all downloaded files. This action is irreversible and deletes all indexed content.

get_job_status

Get status and progress of an async job by ID with real-time updates.

list_active_jobs

List all currently active jobs with their status and progress.