Heuristic
Enhanced MCP server for semantic code search with call-graph proximity, recency ranking, and find-similar-code. Built for AI coding assistants.
What is Heuristic?
Heuristic is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to enhanced mcp server for semantic code search with call-graph proximity, recency ranking, and find-similar-code. built for ai coding assistants.
Enhanced MCP server for semantic code search with call-graph proximity, recency ranking, and find-similar-code. Built for AI coding assistants.
This server falls under the Search & Data Extraction and Developer Tools categories on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Enhanced MCP server for semantic code search with call-graph
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx heuristicConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Heuristic
Heuristic MCP Server is a Node.js MCP server that brings semantic code search to AI coding assistants by indexing your codebase with vector embeddings and ranking results using call-graph proximity and file recency. Unlike simple text search, it understands the meaning of code queries and surfaces the most contextually relevant functions, classes, and modules — including similar code patterns useful for refactoring. Developers using Claude, Cursor, or other MCP-compatible assistants can connect Heuristic to any local repository and ask plain-language questions about their codebase to navigate large projects faster.
Prerequisites
- Node.js 18 or higher (64-bit build recommended for optimal ONNX performance)
- npm package manager
- Internet connectivity for the initial embedding model download (model is cached locally after first run)
- Windows users: Microsoft Visual C++ 2015-2022 Redistributable (x64) if native ONNX bindings fail
- An MCP-compatible client such as Claude Desktop or VS Code with MCP support
Install Heuristic MCP globally
Install the package from npm. The global install makes the heuristic-mcp command available system-wide.
npm install -g @softerist/heuristic-mcpStart the server and index your codebase
Run the start command from within (or pointing to) the repository you want to search. The server will download the embedding model on first run and build the index.
heuristic-mcp --startVerify the server is running
Check the server status to confirm it is healthy and the index build has completed.
heuristic-mcp --statusAdd to Claude Desktop configuration
Register the Heuristic MCP server in claude_desktop_config.json so Claude Desktop can connect to it automatically.
Monitor the cache and index
Use the cache command to watch indexing progress for large repositories or to verify that newly added files have been indexed.
heuristic-mcp --cacheHeuristic Examples
Client configuration
Claude Desktop configuration that connects to the locally running Heuristic MCP server.
{
"mcpServers": {
"heuristic": {
"command": "heuristic-mcp",
"args": ["--start"],
"env": {}
}
}
}Prompts to try
Example prompts that use semantic code search, call-graph proximity ranking, and similar-code discovery.
- "Find the function that handles user authentication in this codebase"
- "Search for all code that performs database connection pooling"
- "Show me code similar to the parseConfig function in src/config.ts"
- "Which modules call the sendEmail utility and how is it used?"
- "Find recently modified code related to error handling and logging"Troubleshooting Heuristic
heuristic-mcp command not found after npm install -g
The npm global bin directory may not be on your PATH. Run 'npm config get prefix' to find it, then add <prefix>/bin to your PATH. On macOS with Homebrew Node: export PATH="$(npm config get prefix)/bin:$PATH"
Native ONNX binding errors on Windows
Install the Microsoft Visual C++ 2015-2022 Redistributable (x64) from the Microsoft website, then reinstall: npm install -g @softerist/heuristic-mcp
Search returns empty or irrelevant results
The embedding index may still be building. Run 'heuristic-mcp --cache' to check progress. For large repositories, allow several minutes for the initial index. Also confirm you started the server from the correct project root directory.
Frequently Asked Questions about Heuristic
What is Heuristic?
Heuristic is a Model Context Protocol (MCP) server that enhanced mcp server for semantic code search with call-graph proximity, recency ranking, and find-similar-code. built for ai coding assistants. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Heuristic?
Follow the installation instructions on the Heuristic GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Heuristic?
Heuristic works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Heuristic free to use?
Yes, Heuristic is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Heuristic Alternatives — Similar Search & Data Extraction Servers
Looking for alternatives to Heuristic? Here are other popular search & data extraction servers you can use with Claude, Cursor, and VS Code.
TrendRadar
★ 58.0kA real-time hotspot monitoring and news aggregation assistant that provides AI-powered analysis of trending topics across multiple platforms via the Model Context Protocol. It enables users to track news and receive automated notifications through va
Scrapling
★ 52.7k🕷️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!
PDF Math Translate
★ 33.9k[EMNLP 2025 Demo] PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译，支持 Google/DeepL/Ollama/OpenAI 等服务，提供 CLI/GUI/MCP/Docker/Zotero
GPT Researcher
★ 27.2kAn autonomous agent that conducts deep research on any data using any LLM providers
Agent Reach
★ 20.1kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Xiaohongshu
★ 13.7kMCP for xiaohongshu.com
Browse More Search & Data Extraction MCP Servers
Explore all search & data extraction servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Heuristic in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Heuristic?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.