Local FAISS

Use the ingest_document tool with: ./path/to/document.pdf Then use query_rag_store to search for: "How does FAISS perform similarity search?"

Claude will retrieve relevant document chunks from your vector store and use them to answer your question.

⚡️Upgrading?Runpip install --upgrade local-faiss-mcp

For DOCX, HTML, EPUB, and 40+ additional formats, install pandoc:

# macOS brew install pandoc # Linux sudo apt install pandoc # Or download from: https://pandoc.org/installing.html

Note: PDF, TXT, and MD work without pandoc.

git clone https://github.com/nonatofabio/local_faiss_mcp.git cd local_faiss_mcp pip install -e .

After installation, you can run the server in three ways:

1. Using the installed command (easiest):

local-faiss-mcp --index-dir /path/to/index/directory

python -m local_faiss_mcp --index-dir /path/to/index/directory

python local_faiss_mcp/server.py --index-dir /path/to/index/directory

- --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)

# Use a larger, more accurate model local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2 # Use a multilingual model local-faiss-mcp --index-dir ./.vector_store --embed paraphrase-multilingual-MiniLM-L12-v2 # Use any Hugging Face sentence-transformers model local-faiss-mcp --index-dir ./.vector_store --embed sentence-transformers/model-name

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.

# Enable re-ranking with default model (BAAI/bge-reranker-base) local-faiss-mcp --index-dir ./.vector_store --rerank # Use a specific re-ranking model local-faiss-mcp --index-dir ./.vector_store --rerank cross-encoder/ms-marco-MiniLM-L-6-v2 # Combine custom embedding and re-ranking local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2 --rerank BAAI/bge-reranker-base

- FAISS retrieves top candidates (10x more than requested)
- Cross-encoder scores each candidate against the query
- Results are re-sorted by relevance score
- Top-k most relevant results are returned

- 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

- 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

The server provides two tools for document management:

Ingest a document into the vector store.

- document(required): Text content OR file path to ingest
- source(optional): Identifier for the document source (default: "unknown")

Auto-detection: Ifdocumentlooks like a file path, it will be automatically parsed.

- Native: TXT, MD, PDF
- With pandoc: DOCX, ODT, HTML, RTF, EPUB, and 40+ formats

{ "document": "FAISS is a library for efficient similarity search...", "source": "faiss_docs.txt" }

{ "document": "./documents/research_paper.pdf" }

Query the vector store for relevant document chunks.

- query(required): The search query text
- top_k(optional): Number of results to return (default: 3)

{ "query": "How does FAISS perform similarity search?", "top_k": 5 }

The server provides MCP prompts to help extract answers and summarize information from retrieved documents:

Extract the most relevant answer from retrieved document chunks with proper citations.

- query(required): The original user query or question
- chunks(required): Retrieved document chunks as JSON array with fields:text,source,distance

Use Case:After querying the RAG store, use this prompt to get a well-formatted answer that cites sources and explains relevance.
- Usequery_rag_storetool to retrieve relevant chunks
- Useextract-answerprompt with the query and results
- Get a comprehensive answer with citations

Create a focused summary from multiple document chunks.

- topic(required): The topic or theme to summarize
- chunks(required): Document chunks to summarize as JSON array
- max_length(optional): Maximum summary length in words (default: 200)

Use Case:Synthesize information from multiple retrieved documents into a concise summary.

In Claude Code, after retrieving documents withquery_rag_store, you can use the prompts like: