nonatofabio/local-faiss-mcp

A Model Context Protocol (MCP) server that provides local vector database functionality using FAISS for Retrieval-Augmented Generation (RAG) applications.
Features
Core Capabilities
- **Local Vector Storage**: Uses FAISS for efficient similarity search without external dependencies
- **Document Ingestion**: Automatically chunks and embeds documents for storage
- **Semantic Search**: Query documents using natural language with sentence embeddings
- **Persistent Storage**: Indexes and metadata are saved to disk
- **MCP Compatible**: Works with any MCP-compatible AI agent or client
v0.2.0 Highlights
- **CLI Tool**: local-faiss command for standalone indexing and search
- **Document Formats**: Native PDF/TXT/MD support, DOCX/HTML/EPUB with pandoc
- **Re-ranking**: Two-stage retrieve and rerank for better results
- **Custom Embeddings**: Choose any Hugging Face embedding model
- **MCP Prompts**: Built-in prompts for answer extraction and summarization
Quickstart
Or use with Claude Code - configure MCP client (see Configuration) and try:
Claude will retrieve relevant document chunks from your vector store and use them to answer your question.
Installation
⚡️ **Upgrading?** Run pip install --upgrade local-faiss-mcp
From PyPI (Recommended)
Optional: Extended Format Support
For DOCX, HTML, EPUB, and 40+ additional formats, install pandoc:
**Note**: PDF, TXT, and MD work without pandoc.
From Source
Usage
Running the Server
After installation, you can run the server in three ways:
**1. Using the installed command (easiest):**
**2. As a Python module:**
**3. For development/testing:**
**Command-line Arguments:**
- --index-dir: Directory to store FAISS index and metadata files (default: current directory)
- --embed: Hugging Face embedding model name (default: all-MiniLM-L6-v2)
- --rerank: Enable re-ranking with specified cross-encoder model (default: BAAI/bge-reranker-base)
**Using a Custom Embedding Model:**
**Using Re-ranking for Better Results:**
Re-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.
**How Re-ranking Works:**
1. FAISS retrieves top candidates (10x more than requested)
2. Cross-encoder scores each candidate against the query
3. Results are re-sorted by relevance score
4. Top-k most relevant results are returned
Popular re-ranking models:
- BAAI/bge-reranker-base - Good balance (default)
- cross-encoder/ms-marco-MiniLM-L-6-v2 - Fast and efficient
- cross-encoder/ms-marco-TinyBERT-L-2-v2 - Very fast, smaller model
The server will:
- Create the index directory if it doesn't exist
- Load existing FAISS index from {index-dir}/faiss.index (or create a new one)
- Load document metadata from {index-dir}/metadata.json (or create new)
- Listen for MCP tool calls via stdin/stdout
Available Tools
The server provides two tools for document management:
1. ingest_document
Ingest a document into the vector store.
**Parameters:**
- document (required): Text content OR file path to ingest
- source (optional): Identifier for the document source (default: "unknown")
**Auto-detection**: If document looks like a file path, it will be automatically parsed.
**Supported formats:**
- Native: TXT, MD, PDF
- With pandoc: DOCX, ODT, HTML, RTF, EPUB, and 40+ formats
**Examples:**
2. query_rag_store
Query the vector store for relevant document chunks.
**Parameters:**
- query (required): The search query text
- top_k (optional): Number of results to return (default: 3)
**Example:**
Available Prompts
The server provides MCP prompts to help extract answers and summarize information from retrieved documents: