Local Search MCP Server
A Model Context Protocol (MCP) server that enables AI assistants to perform semantic search across indexed documents using vector embeddings. Index documents from GitHub repositories and URLs to power natural language queries with contextual results.
Table of Contents
- Features
- Installation
- Configuration
- Usage
- Tools
- Documentation
- Development
- Contributing
- Author
- License
Features
- Semantic Search: Natural language queries over indexed documents using transformer embeddings
- Repository Indexing: Clone and index GitHub repositories with configurable file patterns
- File Downloads: Fetch and index files from URLs with automatic processing
- Async Processing: Non-blocking operations with job progress tracking
- SQLite Storage: Efficient vector storage with optimized similarity search
- MCP Protocol: Full compatibility with Claude Desktop and other MCP applications
Quick Start
The fastest way to get started is using npx (no cloning or building required):
# Run directly with npx
npx -y local-search-mcp
# Or install globally
npm install -g local-search-mcp
MCP Configuration (npx)
Add to Claude Desktop's claude_desktop_config.json:
{
"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"
}
}
}
}
Installation
Prerequisites
- Node.js >= 18.0.0
- npm or yarn package manager
- Git for cloning repositories (development only)
Option 1: NPM Package (Recommended)
# Install globally
npm install -g local-search-mcp
# Or use directly with npx (no installation needed)
npx local-search-mcp
Option 2: From Source (Development)
# Clone the repository
git clone https://github.com/PatrickRuddiman/local-search-mcp.git
cd local-search-mcp
# Install dependencies
npm install
# Build the project
npm run build
MCP Configuration
For NPM package installation:
{
"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"
}
}
}
}
For source installation:
{
"mcpServers": {
"local-search": {
"command": "node",
"args": ["/absolute/path/to/local-search-mcp/build/index.js"],
"env": {
"MCP_DATA_FOLDER": "/optional/custom/data/path",
"MCP_DOCS_FOLDER": "/optional/custom/docs/path"
}
}
}
}
Usage
Once configured, the server provides semantic search capabilities within Claude Desktop and other MCP-compatible applications.
Tools
The Local Search MCP Server provides 7 tools for document indexing and semantic search:
🔍 Search Tools
search_documents
Perform AI-enhanced semantic search with content classification, domain detection, and intelligent recommendations.
Parameters:
query(required): Natural language search queryoptions(optional): Search configuration objectlimit(number, default: 10): Maximum results to returnminScore(number, default: 0.7): Minimum similarity score (0-1)includeMetadata(boolean, default: true): Include metadata in resultsdomainFilter(array): Filter by technology domains (e.g., ["javascript", "python"])contentTypeFilter(array): Filter by content type ("code", "docs", "config", "mixed")languageFilter(array): Filter by programming language (e.g., ["typescript", "javascript"])minQualityScore(number): Minimum content quality score (0-1)minAuthorityScore(number): Minimum source authority score (0-1)
Example:
{
"query": "async await promises javascript",
"options": {
"limit": 5,
"domainFilter": ["javascript"],
"contentTypeFilter": ["code", "docs"]
}
}
get_file_details
Retrieve detailed content of a specific file with surrounding chunk context.
Parameters:
filePath(required): Absolute path to filechunkIndex(optional): Specific chunk to retrieve with surrounding contextcontextSize(number, default: 3): Number of chunks to include before and after target chunk
📦 Content Management Tools
fetch_repo
Clone a Git repository (GitHub, Azure DevOps, etc.) using repomix, convert to markdown, and add to searchable index. Returns job ID for progress tracking.
Parameters:
repoUrl(required): Git repository URLbranch(optional): Branch/tag/commit, defaults to main/masteroptions(optional): Repository processing optionsincludePatterns(array, default: ["/*.md", "/.mdx", "**/.txt", "/*.json", "/.rst", "**/.yml", "**/*.yaml"]): File patterns to includeexcludePatterns(array, default: ["/node_modules/"]): File patterns to excludeoutputStyle(string, default: "markdown"): Output format (fixed to markdown)removeComments(boolean, default: false): Remove comments from code filesshowLineNumbers(boolean, default: true): Show line numbers in output
Example:
{
"repoUrl": "https://github.com/microsoft/TypeScript",
"branch": "main",
"options": {
"includePatterns": ["**/*.md", "**/*.ts"],
"excludePatterns": ["**/node_modules/**", "**/tests/**"]
}
}
fetch_file
Download a single file from a URL and add it to the searchable index. Returns job ID for progress tracking.
Parameters:
url(required): URL of file to downloadfilename(required): Desired filename for savingoptions(optional): Download optionsoverwrite(boolean, default: true): Whether to overwrite existing filesindexAfterSave(boolean, default: true): Automatically index after downloadmaxFileSizeMB(number, default: 1024): Maximum file size in MB
remove_file
Delete a file and all its associated chunks and embeddings from the index.
Parameters:
filePath(required): Absolute path to file to remove
flush_all
Flush the entire database and all downloaded files. WARNING: This action is irreversible and will delete all indexed content, documents, and cached files.
Parameters: None
What gets deleted:
- All vector embeddings and document chunks from the database
- All recommendation and learning data
- All downloaded files from the
fetcheddirectory - All cloned repositories from the
repositoriesdirectory - All temporary files from the
tempdirectory - All active background jobs are cancelled
Example:
{
"name": "flush_all",
"arguments": {}
}
⚙️ Job Management Tools
get_job_status
Get status and progress of an async job by ID with real-time accurate progress.
Parameters:
jobId(required): Job ID returned from fetch_* operations
Returns:
- Job status: "running", "completed", or "failed"
- Progress percentage (0-100)
- Duration and timestamps
- Error message if failed
- Result data if completed
list_active_jobs
List all currently active (running) jobs with their status and progress.
Parameters: None
Returns:
- List of active jobs with progress
- Job statistics (total, completed, failed, average duration)
- Real-time progress updates
Documentation
For detailed technical documentation:
- Architecture - System design and processing pipeline
- API Reference - Complete tool specifications and types
- Performance - Optimization guides and benchmarks
- Usage Examples - Sample integrations and workflows
Development
npm install
npm run build
npm run dev # Development with hot reload
Configuration
Environment Variables
Set optional environment variables for custom paths:
MCP_DATA_FOLDER- Custom database and logs directory (defaults to platform-specific user data folder)MCP_DOCS_FOLDER- Custom document storage directory (defaults to platform-specific user documents folder)
Supported File Types
The server processes these file types:
- Documentation:
.md,.txt,.rst,.yaml,.yml - Data:
.json,.csv - Code:
.js,.ts,.py,.java,.c,.cpp,.html,.css - Files up to 1GB are supported
Acknowledgments
- @xenova/transformers - JavaScript ML models for embeddings
- sqlite-vec - Native vector search in SQLite
- better-sqlite3 - Fast SQLite3 bindings
- Model Context Protocol - Standard for AI tool integration
- repomix - Repository processing utility
Release Process
This project uses automated semantic versioning and publishing through GitHub Actions and semantic-release.
Commit Message Format
Follow Conventional Commits specification:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Types that trigger releases:
feat:- New features (minor version bump)fix:- Bug fixes (patch version bump)perf:- Performance improvements (patch version bump)BREAKING CHANGE:- Breaking changes (major version bump)
Other types (no release):
docs:- Documentation changesstyle:- Code formattingrefactor:- Code refactoringtest:- Adding testschore:- Build process or auxiliary tool changes
Contributing
- Fork the repository
- Create a feature branch with descriptive name
- Make changes following conventional commit format
- Submit a pull request targeting the
mainbranch - Ensure all CI checks pass before requesting review
Author
Patrick Ruddiman
GitHub
License
MIT - see LICENSE for details.