Local FAISS MCP Server

1# Local FAISS MCP Server
2 
3<!-- mcp-name: io.github.nonatofabio/local-faiss-mcp -->
4 
5[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
7[![Tests](https://github.com/nonatofabio/local_faiss_mcp/workflows/Tests/badge.svg)](https://github.com/nonatofabio/local_faiss_mcp/actions)
8[![PyPI version](https://badge.fury.io/py/local-faiss-mcp.svg)](https://badge.fury.io/py/local-faiss-mcp)
9 
10A Model Context Protocol (MCP) server that provides local vector database functionality using FAISS for Retrieval-Augmented Generation (RAG) applications.
11 
12![demo](./static/demo.gif)
13 
14## Features
15 
16### Core Capabilities
17- **Local Vector Storage**: Uses FAISS for efficient similarity search without external dependencies
18- **Document Ingestion**: Automatically chunks and embeds documents for storage
19- **Semantic Search**: Query documents using natural language with sentence embeddings
20- **Persistent Storage**: Indexes and metadata are saved to disk
21- **MCP Compatible**: Works with any MCP-compatible AI agent or client
22 
23### v0.2.0 Highlights
24- **CLI Tool**: `local-faiss` command for standalone indexing and search
25- **Document Formats**: Native PDF/TXT/MD support, DOCX/HTML/EPUB with pandoc
26- **Re-ranking**: Two-stage retrieve and rerank for better results
27- **Custom Embeddings**: Choose any Hugging Face embedding model
28- **MCP Prompts**: Built-in prompts for answer extraction and summarization
29 
30## Quickstart
31 
32```bash
33# Install
34pip install local-faiss-mcp
35 
36# Index documents
37local-faiss index document.pdf
38 
39# Search
40local-faiss search "What is this document about?"
41```
42 
43Or use with Claude Code - configure MCP client (see [Configuration](#configuration-with-mcp-clients)) and try:
44 
45```
46Use the ingest_document tool with: ./path/to/document.pdf
47Then use query_rag_store to search for: "How does FAISS perform similarity search?"
48```
49 
50Claude will retrieve relevant document chunks from your vector store and use them to answer your question.
51 
52## Installation
53 
54⚡️ **Upgrading?** Run `pip install --upgrade local-faiss-mcp`
55 
56### From PyPI (Recommended)
57 
58```bash
59pip install local-faiss-mcp
60```
61 
62### Optional: Extended Format Support
63 
64For DOCX, HTML, EPUB, and 40+ additional formats, install pandoc:
65 
66```bash
67# macOS
68brew install pandoc
69 
70# Linux
71sudo apt install pandoc
72 
73# Or download from: https://pandoc.org/installing.html
74```
75 
76**Note**: PDF, TXT, and MD work without pandoc.
77 
78### From Source
79 
80```bash
81git clone https://github.com/nonatofabio/local_faiss_mcp.git
82cd local_faiss_mcp
83pip install -e .
84```
85 
86## Usage
87 
88### Running the Server
89 
90After installation, you can run the server in three ways:
91 
92**1. Using the installed command (easiest):**
93```bash
94local-faiss-mcp --index-dir /path/to/index/directory
95```
96 
97**2. As a Python module:**
98```bash
99python -m local_faiss_mcp --index-dir /path/to/index/directory
100```
101 
102**3. For development/testing:**
103```bash
104python local_faiss_mcp/server.py --index-dir /path/to/index/directory
105```
106 
107**Command-line Arguments:**
108- `--index-dir`: Directory to store FAISS index and metadata files (default: current directory)
109- `--embed`: Hugging Face embedding model name (default: `all-MiniLM-L6-v2`)
110- `--rerank`: Enable re-ranking with specified cross-encoder model (default: `BAAI/bge-reranker-base`)
111 
112**Using a Custom Embedding Model:**
113```bash
114# Use a larger, more accurate model
115local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2
116 
117# Use a multilingual model
118local-faiss-mcp --index-dir ./.vector_store --embed paraphrase-multilingual-MiniLM-L12-v2
119 
120# Use any Hugging Face sentence-transformers model
121local-faiss-mcp --index-dir ./.vector_store --embed sentence-transformers/model-name
122```
123 
124**Using Re-ranking for Better Results:**
125 
126Re-ranking uses a cross-encoder model to reorder FAISS results for improved relevance. This two-stage "retrieve and rerank" approach is common in production search systems.
127 
128```bash
129# Enable re-ranking with default model (BAAI/bge-reranker-base)
130local-faiss-mcp --index-dir ./.vector_store --rerank
131 
132# Use a specific re-ranking model
133local-faiss-mcp --index-dir ./.vector_store --rerank cross-encoder/ms-marco-MiniLM-L-6-v2
134 
135# Combine custom embedding and re-ranking
136local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2 --rerank BAAI/bge-reranker-base
137```
138 
139**How Re-ranking Works:**
1401. FAISS retrieves top candidates (10x more than requested)
1412. Cross-encoder scores each candidate against the query
1423. Results are re-sorted by relevance score
1434. Top-k most relevant results are returned
144 
145Popular re-ranking models:
146- `BAAI/bge-reranker-base` - Good balance (default)
147- `cross-encoder/ms-marco-MiniLM-L-6-v2` - Fast and efficient
148- `cross-encoder/ms-marco-TinyBERT-L-2-v2` - Very fast, smaller model
149 
150The server will:
151- Create the index directory if it doesn't exist
152- Load existing FAISS index from `{index-dir}/faiss.index` (or create a new one)
153- Load document metadata from `{index-dir}/metadata.json` (or create new)
154- Listen for MCP tool calls via stdin/stdout
155 
156### Available Tools
157 
158The server provides two tools for document management:
159 
160#### 1. ingest_document
161 
162Ingest a document into the vector store.
163 
164**Parameters:**
165- `document` (required): Text content OR file path to ingest
166- `source` (optional): Identifier for the document source (default: "unknown")
167 
168**Auto-detection**: If `document` looks like a file path, it will be automatically parsed.
169 
170**Supported formats:**
171- Native: TXT, MD, PDF
172- With pandoc: DOCX, ODT, HTML, RTF, EPUB, and 40+ formats
173 
174**Examples:**
175```json
176{
177  "document": "FAISS is a library for efficient similarity search...",
178  "source": "faiss_docs.txt"
179}
180```
181 
182```json
183{
184  "document": "./documents/research_paper.pdf"
185}
186```
187 
188#### 2. query_rag_store
189 
190Query the vector store for relevant document chunks.
191 
192**Parameters:**
193- `query` (required): The search query text
194- `top_k` (optional): Number of results to return (default: 3)
195 
196**Example:**
197```json
198{
199  "query": "How does FAISS perform similarity search?",
200  "top_k": 5
201}
202```
203 
204### Available Prompts
205 
206The server provides MCP prompts to help extract answers and summarize information from retrieved documents:
207 
208#### 1. extract-answer
209 
210Extract the most relevant answer from retrieved document chunks with proper citations.
211 
212**Arguments:**
213- `query` (required): The original user query or question
214- `chunks` (required): Retrieved document chunks as JSON array with fields: `text`, `source`, `distance`
215 
216**Use Case:** After querying the RAG store, use this prompt to get a well-formatted answer that cites sources and explains relevance.
217 
218**Example workflow in Claude:**
2191. Use `query_rag_store` tool to retrieve relevant chunks
2202. Use `extract-answer` prompt with the query and results
2213. Get a comprehensive answer with citations
222 
223#### 2. summarize-documents
224 
225Create a focused summary from multiple document chunks.
226 
227**Arguments:**
228- `topic` (required): The topic or theme to summarize
229- `chunks` (required): Document chunks to summarize as JSON array
230- `max_length` (optional): Maximum summary length in words (default: 200)
231 
232**Use Case:** Synthesize information from multiple retrieved documents into a concise summary.
233 
234**Example Usage:**
235 
236In Claude Code, after retrieving documents with `query_rag_store`, you can use the prompts like:
237 
238```
239Use the extract-answer prompt with:
240- query: "What is FAISS?"
241- chunks: [the JSON results from query_rag_store]
242```
243 
244The prompts will guide the LLM to provide structured, citation-backed answers based on your vector store data.
245 
246## Command-Line Interface
247 
248The `local-faiss` CLI provides standalone document indexing and search capabilities.
249 
250### Index Command
251 
252Index documents from the command line:
253 
254```bash
255# Index single file
256local-faiss index document.pdf
257 
258# Index multiple files
259local-faiss index doc1.pdf doc2.txt doc3.md
260 
261# Index all files in folder
262local-faiss index documents/
263 
264# Index recursively
265local-faiss index -r documents/
266 
267# Index with glob pattern
268local-faiss index "docs/**/*.pdf"
269```
270 
271**Configuration**: The CLI automatically uses MCP configuration from:
2721. `./.mcp.json` (local/project-specific)
2732. `~/.claude/.mcp.json` (Claude Code config)
2743. `~/.mcp.json` (fallback)
275 
276If no config exists, creates `./.mcp.json` with default settings (`./.vector_store`).
277 
278**Supported formats:**
279- **Native**: TXT, MD, PDF (always available)
280- **With pandoc**: DOCX, ODT, HTML, RTF, EPUB, etc.
281  - Install: `brew install pandoc` (macOS) or `apt install pandoc` (Linux)
282 
283### Search Command
284 
285Search the indexed documents:
286 
287```bash
288# Basic search
289local-faiss search "What is FAISS?"
290 
291# Get more results
292local-faiss search -k 5 "similarity search algorithms"
293```
294 
295Results show:
296- Source file path
297- FAISS distance score
298- Re-rank score (if enabled in MCP config)
299- Text preview (first 300 characters)
300 
301### CLI Features
302 
303- ✅ **Incremental indexing**: Adds to existing index, doesn't overwrite
304- ✅ **Progress output**: Shows indexing progress for each file
305- ✅ **Shared config**: Uses same settings as MCP server
306- ✅ **Auto-detection**: Supports glob patterns and recursive folders
307- ✅ **Format support**: Handles PDF, TXT, MD natively; DOCX+ with pandoc
308 
309## Configuration with MCP Clients
310 
311### Claude Code
312 
313Add this server to your Claude Code MCP configuration (`.mcp.json`):
314 
315**User-wide configuration** (`~/.claude/.mcp.json`):
316```json
317{
318  "mcpServers": {
319    "local-faiss-mcp": {
320      "command": "local-faiss-mcp"
321    }
322  }
323}
324```
325 
326**With custom index directory**:
327```json
328{
329  "mcpServers": {
330    "local-faiss-mcp": {
331      "command": "local-faiss-mcp",
332      "args": [
333        "--index-dir",
334        "/home/user/vector_indexes/my_project"
335      ]
336    }
337  }
338}
339```
340 
341**With custom embedding model**:
342```json
343{
344  "mcpServers": {
345    "local-faiss-mcp": {
346      "command": "local-faiss-mcp",
347      "args": [
348        "--index-dir",
349        "./.vector_store",
350        "--embed",
351        "all-mpnet-base-v2"
352      ]
353    }
354  }
355}
356```
357 
358**With re-ranking enabled**:
359```json
360{
361  "mcpServers": {
362    "local-faiss-mcp": {
363      "command": "local-faiss-mcp",
364      "args": [
365        "--index-dir",
366        "./.vector_store",
367        "--rerank"
368      ]
369    }
370  }
371}
372```
373 
374**Full configuration with embedding and re-ranking**:
375```json
376{
377  "mcpServers": {
378    "local-faiss-mcp": {
379      "command": "local-faiss-mcp",
380      "args": [
381        "--index-dir",
382        "./.vector_store",
383        "--embed",
384        "all-mpnet-base-v2",
385        "--rerank",
386        "BAAI/bge-reranker-base"
387      ]
388    }
389  }
390}
391```
392 
393**Project-specific configuration** (`./.mcp.json` in your project):
394```json
395{
396  "mcpServers": {
397    "local-faiss-mcp": {
398      "command": "local-faiss-mcp",
399      "args": [
400        "--index-dir",
401        "./.vector_store"
402      ]
403    }
404  }
405}
406```
407 
408**Alternative: Using Python module** (if the command isn't in PATH):
409```json
410{
411  "mcpServers": {
412    "local-faiss-mcp": {
413      "command": "python",
414      "args": ["-m", "local_faiss_mcp", "--index-dir", "./.vector_store"]
415    }
416  }
417}
418```
419 
420### Claude Desktop
421 
422Add this server to your Claude Desktop configuration:
423 
424```json
425{
426  "mcpServers": {
427    "local-faiss-mcp": {
428      "command": "local-faiss-mcp",
429      "args": ["--index-dir", "/path/to/index/directory"]
430    }
431  }
432}
433```
434 
435## Architecture
436 
437- **Embedding Model**: Configurable via `--embed` flag (default: `all-MiniLM-L6-v2` with 384 dimensions)
438  - Supports any Hugging Face sentence-transformers model
439  - Automatically detects embedding dimensions
440  - Model choice persisted with the index
441- **Index Type**: FAISS IndexFlatL2 for exact L2 distance search
442- **Chunking**: Documents are split into ~500 word chunks with 50 word overlap
443- **Storage**: Index saved as `faiss.index`, metadata saved as `metadata.json`
444 
445### Choosing an Embedding Model
446 
447Different models offer different trade-offs:
448 
449| Model | Dimensions | Speed | Quality | Use Case |
450|-------|-----------|-------|---------|----------|
451| `all-MiniLM-L6-v2` | 384 | Fast | Good | Default, balanced performance |
452| `all-mpnet-base-v2` | 768 | Medium | Better | Higher quality embeddings |
453| `paraphrase-multilingual-MiniLM-L12-v2` | 384 | Fast | Good | Multilingual support |
454| `all-MiniLM-L12-v2` | 384 | Medium | Better | Better quality at same size |
455 
456**Important:** Once you create an index with a specific model, you must use the same model for subsequent runs. The server will detect dimension mismatches and warn you.
457 
458## Development
459 
460### Standalone Test
461 
462Test the FAISS vector store functionality without MCP infrastructure:
463 
464```bash
465source venv/bin/activate
466python test_standalone.py
467```
468 
469This test:
470- Initializes the vector store
471- Ingests sample documents
472- Performs semantic search queries
473- Tests persistence and reload
474- Cleans up test files
475 
476### Unit Tests
477 
478Run the complete test suite:
479```bash
480pytest tests/ -v
481```
482 
483Run specific test files:
484```bash
485# Test embedding model functionality
486pytest tests/test_embedding_models.py -v
487 
488# Run standalone integration test
489python tests/test_standalone.py
490```
491 
492The test suite includes:
493- **test_embedding_models.py**: Comprehensive tests for custom embedding models, dimension detection, and compatibility
494- **test_standalone.py**: End-to-end integration test without MCP infrastructure
495 
496## License
497 
498MIT
499