mcp-vector-search
Semantic search for your documents, available to AI agents via MCP.
Index documentation, code, and knowledge bases with semantic embeddings. AI assistants can search on-demand without loading everything into context.
;; .mcp-vector-search/config.edn
{:sources [{:path "/docs/**/*.md"}]}
# Search from Claude Code
"Find authentication documentation"
→ Returns relevant docs based on semantic similarity
Quick Links: Quick Start · Installation · What & Why · Advanced Features
Table of Contents
Quick Start
1. Install the MCP server (requires Clojure CLI tools):
# Add to ~/.clojure/deps.edn
{:aliases
{:mcp-vector-search
{:replace-paths []
:replace-deps {org.hugoduncan/mcp-vector-search
{:git/url "https://github.com/hugoduncan/mcp-vector-search"
:git/sha "LATEST_SHA_HERE"}
org.clojure/clojure {:mvn/version "1.12.3"}}
:jvm-opts ["--enable-native-access=ALL-UNNAMED"]
:exec-fn mcp-vector-search.main/start}}}
# Configure Claude Code
claude mcp add mcp-vector-search -- $(which clojure) -X:mcp-vector-search
2. Create config file at ~/.mcp-vector-search/config.edn or .mcp-vector-search/config.edn:
{:sources [{:path "/path/to/your/docs/**/*.md"}]}
3. Restart Claude Code - the search tool is now available.
4. Search from Claude Code:
"Search for authentication best practices"
"Find code examples for user validation"
"Show me documentation about API rate limiting"
The assistant will use the search tool to find relevant content semantically, without you loading all documents into context.
What & Why
What It Does
mcp-vector-search is an MCP server that:
- Indexes documents using semantic embeddings (AllMiniLmL6V2 model)
- Provides a search tool to AI assistants via the Model Context Protocol
- Enables semantic search - find content by meaning, not just keywords
- Filters by metadata - narrow searches to specific projects, categories, or file types
- Works as a library - embed in your own MCP servers with bundled documentation
Why Use It
Expand what's accessible, not what's loaded. AI agents have limited context windows. Instead of loading all documentation upfront, they search when needed.
Key benefits:
- Work with knowledge bases larger than context windows
- Discover related content through semantic similarity
- Retrieve information just-in-time, not speculatively
- The search tool doesn't consume context - only results do
When to use:
- Large documentation sets (hundreds of pages)
- Multi-project codebases (find patterns across projects)
- Historical context (design docs, decision logs)
- API references (look up functions and examples as needed)
- Custom MCP servers needing semantic search over bundled documentation
See doc/about.md for a detailed explanation of the problem and solution.
Library usage: mcp-vector-search can be embedded in your own MCP servers to provide semantic search over bundled resources. See doc/library-usage.md for details.
Installation
Prerequisites
- Clojure CLI tools
- Java 11+ (required for embedding model)
Configure Clojure Alias
Add to ~/.clojure/deps.edn:
{:aliases
{:mcp-vector-search
{:replace-paths []
:replace-deps {org.hugoduncan/mcp-vector-search
{:git/url "https://github.com/hugoduncan/mcp-vector-search"
:git/sha "LATEST_SHA_HERE"}
org.clojure/clojure {:mvn/version "1.12.3"}}
:jvm-opts ["--enable-native-access=ALL-UNNAMED"]
:exec-fn mcp-vector-search.main/start}}}
Note: Replace LATEST_SHA_HERE with the latest commit SHA from this repository.
Add to MCP Client
Claude Code:
claude mcp add mcp-vector-search -- $(which clojure) -X:mcp-vector-search
Claude Desktop, Cline, and other MCP clients: See doc/install.md for setup instructions and troubleshooting.
Basic Configuration
Configuration file location (first found is used):
.mcp-vector-search/config.edn (project-specific)~/.mcp-vector-search/config.edn (global)
Minimal Example
{:sources [{:path "/docs/**/*.md"}]}
Indexes all markdown files recursively under /docs/.
Path Patterns and Metadata
Path specs support globs (*, **), regex captures, and custom metadata:
;; Basic: recursive glob
{:sources [{:path "/docs/**/*.md"}]}