Local Faiss MCP

🚀 Local FAISS MCP Server

This is a Model Context Protocol (MCP) server that offers local vector database functionality using FAISS for Retrieval-Augmented Generation (RAG) applications. It enables efficient similarity search and seamless integration with MCP-compatible AI agents.

✨ Features

Core Capabilities

• Local Vector Storage: Utilizes FAISS for efficient similarity search without relying on external dependencies.
• Document Ingestion: Automatically chunks and embeds documents for storage.
• Semantic Search: Allows querying documents using natural language with sentence embeddings.
• Persistent Storage: Saves indexes and metadata to disk.
• MCP Compatible: Works with any MCP-compatible AI agent or client.

v0.2.0 Highlights

• CLI Tool: The local-faiss command enables standalone indexing and search.
• Document Formats: Natively supports PDF/TXT/MD, and supports DOCX/HTML/EPUB with pandoc.
• Re-ranking: Implements a two-stage retrieve and rerank process for better results.
• Custom Embeddings: Allows you to choose any Hugging Face embedding model.
• MCP Prompts: Comes with built-in prompts for answer extraction and summarization.

🚀 Quick Start

# Install
pip install local-faiss-mcp

# Index documents
local-faiss index document.pdf

# Search
local-faiss search "What is this document about?"

Or use it with Claude Code - configure the MCP client (see Configuration) and try:

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.

📦 Installation

⚡️ Upgrading? Run pip install --upgrade local-faiss-mcp

From PyPI (Recommended)

pip install local-faiss-mcp

Optional: Extended Format Support

For DOCX, HTML, EPUB, and over 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.

From Source

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

💻 Usage

Running the Server

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

2. As a Python module:

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

3. For development/testing:

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

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:

# 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

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.

# 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

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:

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

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

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:

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

Available Prompts

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

1. extract-answer

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

Arguments:

• 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.

Example workflow in Claude:

1. Use query_rag_store tool to retrieve relevant chunks.
2. Use extract-answer prompt with the query and results.
3. Get a comprehensive answer with citations.

2. summarize-documents

Create a focused summary from multiple document chunks.

Arguments:

• 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.

Example Usage:

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

Use the extract-answer prompt with:
- query: "What is FAISS?"
- chunks: [the JSON results from query_rag_store]

The prompts will guide the LLM to provide structured, citation-backed answers based on your vector store data.

📚 Command-Line Interface

The local-faiss CLI provides standalone document indexing and search capabilities.

Index Command

Index documents from the command line:

# Index single file
local-faiss index document.pdf

# Index multiple files
local-faiss index doc1.pdf doc2.txt doc3.md

# Index all files in folder
local-faiss index documents/

# Index recursively
local-faiss index -r documents/

# Index with glob pattern
local-faiss index "docs/**/*.pdf"

Configuration: The CLI automatically uses MCP configuration from:

1. ./.mcp.json (local/project-specific).
2. ~/.claude/.mcp.json (Claude Code config).
3. ~/.mcp.json (fallback).

If no config exists, creates ./.mcp.json with default settings (./.vector_store).

Supported formats:

• Native: TXT, MD, PDF (always available).
• With pandoc: DOCX, ODT, HTML, RTF, EPUB, etc.
  • Install: brew install pandoc (macOS) or apt install pandoc (Linux).

Search Command

Search the indexed documents:

# Basic search
local-faiss search "What is FAISS?"

# Get more results
local-faiss search -k 5 "similarity search algorithms"

Results show:

• Source file path.
• FAISS distance score.
• Re-rank score (if enabled in MCP config).
• Text preview (first 300 characters).

CLI Features

• ✅ Incremental indexing: Adds to existing index, doesn't overwrite.
• ✅ Progress output: Shows indexing progress for each file.
• ✅ Shared config: Uses same settings as MCP server.
• ✅ Auto-detection: Supports glob patterns and recursive folders.
• ✅ Format support: Handles PDF, TXT, MD natively; DOCX+ with pandoc.

📚 Configuration with MCP Clients

Claude Code

Add this server to your Claude Code MCP configuration (.mcp.json):

User-wide configuration (~/.claude/.mcp.json):

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp"
    }
  }
}

With custom index directory:

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "/home/user/vector_indexes/my_project"
      ]
    }
  }
}

With custom embedding model:

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--embed",
        "all-mpnet-base-v2"
      ]
    }
  }
}

With re-ranking enabled:

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--rerank"
      ]
    }
  }
}

Full configuration with embedding and re-ranking:

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--embed",
        "all-mpnet-base-v2",
        "--rerank",
        "BAAI/bge-reranker-base"
      ]
    }
  }
}

Project-specific configuration (./.mcp.json in your project):

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store"
      ]
    }
  }
}

Alternative: Using Python module (if the command isn't in PATH):

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "python",
      "args": ["-m", "local_faiss_mcp", "--index-dir", "./.vector_store"]
    }
  }
}

Claude Desktop

Add this server to your Claude Desktop configuration:

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": ["--index-dir", "/path/to/index/directory"]
    }
  }
}

🔧 Architecture

• Embedding Model: Configurable via --embed flag (default: all-MiniLM-L6-v2 with 384 dimensions).
  • Supports any Hugging Face sentence-transformers model.
  • Automatically detects embedding dimensions.
  • Model choice persisted with the index.
• Index Type: FAISS IndexFlatL2 for exact L2 distance search.
• Chunking: Documents are split into ~500 word chunks with 50 word overlap.
• Storage: Index saved as faiss.index, metadata saved as metadata.json.

Choosing an Embedding Model

Different models offer different trade-offs:

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.

📚 Development

Standalone Test

Test the FAISS vector store functionality without MCP infrastructure:

source venv/bin/activate
python test_standalone.py

This test:

• Initializes the vector store.
• Ingests sample documents.
• Performs semantic search queries.
• Tests persistence and reload.
• Cleans up test files.

Unit Tests

Run the complete test suite:

pytest tests/ -v

Run specific test files:

# Test embedding model functionality
pytest tests/test_embedding_models.py -v

# Run standalone integration test
python tests/test_standalone.py

The test suite includes:

• test_embedding_models.py: Comprehensive tests for custom embedding models, dimension detection, and compatibility.
• test_standalone.py: End-to-end integration test without MCP infrastructure.

📄 License

MIT