mcp-semantic-search
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-semantic-search search for rate limiting strategies in the gateway specs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π mcp-semantic-search
Ask your specs a question instead of grepping them.
An MCP server & CLI that gives AI agents local semantic search over markdown docs β running 100% on your machine by default.
Why use this?
Traditional grep misses ideas that don't match exact keywords.
mcp-semantic-search understands intent across your local specs, RFCs, and internal docs.
$ mcp-semantic-search search "how do we stop repeated failed logins"
--- Result 1 [0.688] content ---
file: auth.md
section: Sessions > Credential attempts
After five consecutive bad passwords the account enters a 15-minute
cooling-off period. The counter resets on any successful sign-in.
--- Result 2 [0.541] content ---
file: gateway.md
section: Rate limits > Edge throttling
A single IP address is capped at 20 requests per minute against
/session endpoints. Anything beyond that receives a 429 before it
ever reaches the application.Notice: Neither chunk contains the words "failed" or "login" β
grep -ri "failed login"returns nothing at all. Semantic search finds both halves of the answer: the account lockout in the auth spec, and the network throttle that backs it up in a different file with entirely different vocabulary.
Related MCP server: Inkdex
Key Features
π§± Structure-Aware Chunking β Splits markdown on heading boundaries (
H1βH4) without breaking code blocks or tables.π Local & Private β Runs via LanceDB & Ollama. Zero docs leave your machine.
πΊοΈ Document Maps β Generates outline (
toc) chunks so agents can scan doc structures before reading details.β‘ Zero-Overhead Indexing β File hashes ensure re-indexing only happens when files actually change.
π― Targeted Filtering β Filter search by filename, heading, or chunk type (
content,code,table,toc).
Quick Start
1. Requirements & Build
Requires Node.js 22+ and Ollama (or a Gemini API key).
# Pull default model
ollama pull qwen3-embedding:0.6b
# Clone & Build
git clone <repo-url> mcp-semantic-search
cd mcp-semantic-search
npm install && npm run build2. Run locally (CLI)
Inside the target repository you want to index:
cd ~/projects/my-app
echo '.mcp-search/' >> .gitignore
/path/to/mcp-semantic-search index
/path/to/mcp-semantic-search search "how are expired sessions cleaned up"Setup as an MCP Server
Add to your project's .mcp.json:
{
"mcpServers": {
"specs": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/mcp-semantic-search/dist/index.js"]
}
}
}MCP Tools Exposed
indexβ Indexes your markdown specs directory (setreindex: trueto force rebuild).searchβ Queries indexed documents (query,file,section,chunk_type,limit,min_score).statusβ Checks index health, chunk counts, and staleness.
Agent Prompting Tip (
CLAUDE.md): Add this to your project'sCLAUDE.md: "Search specs using thespecsMCP server. Runindexfirst ifstatusshows the index as missing or stale."
Configuration
Set environment variables in your shell or directly inside .mcp.json under the "env" block.
Global Settings
Variable | Default | Purpose |
|
| Vector provider: |
|
| Absolute path to markdown specs |
|
| Where LanceDB index is stored |
|
| Default similarity threshold |
Ollama Backend (Default)
Variable | Default | Purpose |
|
| Endpoint for Ollama daemon |
|
| Embedding model to use |
Gemini Backend (Cloud Option)
Variable | Default | Purpose |
| (Required) | Required when |
|
| Embedding model to use |
|
| Vector width (128β3072) |
Note: Changing backends automatically triggers a clean index rebuild on the next run.
Example .mcp.json with Custom Config
{
"mcpServers": {
"specs": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/mcp-semantic-search/dist/index.js"],
"env": {
"SPECS_DIR": "/absolute/path/to/my-app/docs",
"EMBEDDING_BACKEND": "gemini",
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}CLI Options
mcp-semantic-search search <query> [options]Flag | Description | Default |
| Filter by matching filename | β |
| Filter by matching section heading | β |
|
| All |
| Max results to return |
|
| Similarity floor (0.0β1.0) |
|
| Output raw JSON instead of plain text |
|
License
MIT
Available Tools
3 toolsindexA
Index the specs/ directory in the current project (app). Automatically skips if content hasn't changed since last index.
Inputs: reindex.
searchA
Semantic search over indexed specs in app. Returns relevant markdown chunks ranked by similarity. Optionally filter by file, section heading, or chunk type.
Inputs: query (required), file, limit, section, +2 more.
statusA
Show index status for the current project.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 3 tools
Each tool has a distinct, non-overlapping purpose: index builds the search index, search queries it, and status shows its state. No ambiguity exists among them.
All three tool names are single lowercase words (index, search, status) that clearly describe their action. The naming pattern is uniform and predictable.
Three tools are exactly right for a focused semantic search MCP server: index, search, and status cover the essential operations without excess or deficiency.
The set covers the core lifecycle (index, search, status) but lacks an explicit operation to clear or delete the index. This minor gap is acceptable for most use cases.
Related MCP Connectors
Open-source Obsidian for MDX - edit local docs with agent assistance
Persistent memory for AI agents. Search, store, and recall across sessions.
Memory system for AI agents with semantic search. Store and recall memories with ease.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI agents to search local Markdown documents using natural language, with automatic indexing and section-level retrieval.101MIT
- AlicenseAqualityDmaintenanceEnables semantic search over local markdown documentation by indexing files and ranking results using vector similarity and BM25 fusion.1Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI coding agents to perform semantic code search locally, finding code by meaning rather than exact keywords.3MIT
- AlicenseNot gradedqualityCmaintenanceProvides fully local long-term memory for AI agents by enabling semantic search over notes and session logs using Ollama embeddings, with no external APIs or databases.MIT