Local FAISS MCP Server
Local FAISS vector database for RAG with document ingestion, semantic search, and MCP prompts.
Open source Open in the app JSON README (API)
About
Local FAISS vector database for RAG with document ingestion, semantic search, and MCP prompts.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- nonatofabio
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.0-rc.3
- Stars
- 33
- Forks
- 12
- Open pull requests
- 1
- Last push
- 2026-04-24T21:21:39Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:55
- Updated
- 2026-08-29 04:00:55
- Origin id
io.github.nonatofabio/local-faiss-mcp
README
# Local FAISS MCP Server
<!-- mcp-name: io.github.nonatofabio/local-faiss-mcp -->
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/nonatofabio/local_faiss_mcp/actions)
[](https://badge.fury.io/py/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
```bash
# Install
pip install local-faiss-mcp
# Index documents
local-faiss index document.pdf
# Search
local-faiss search "What is this document about?"
```
Or use with Claude Code - configure MCP client (see [Configuration](#configuration-with-mcp-clients)) 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)
```bash
pip install local-faiss-mcp
```
### Optional: Extended Format Support
For DOCX, HTML, EPUB, and 40+ additional formats, install pandoc:
```bash
# 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
```bash
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):**
```bash
local-faiss-mcp --index-dir /path/to/index/directory
```
**2. As a Python module:**
```bash
python -m local_faiss_mcp --index-dir /path/to/index/directory
```
**3. For development/testing:**
```bash
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:**
```bash
# 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.
```bash
# 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:**
```json
{
"document": "FAISS is a library for efficient similarity search...",
"source": "faiss_docs.txt"
}
```
```json
{
"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:**
```json
{
"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:
```bash
# 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:
```bash
# 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`):
```json
{
"mcpServers": {
"local-faiss-mcp": {
"command": "local-faiss-mcp"
}
}
}
```
**With custom index directory**:
```json
{
"mcpServers": {
"local-faiss-mcp": {
"command": "local-faiss-mcp",
"args": [
"--index-dir",
"/home/user/vector_indexes/my_project"
]
}
}
}
```
**With custom embedding model**:
```json
{
"mcpServers": {
"local-faiss-mcp": {
"command": "local-faiss-mcp",
"args": [
"--index-dir",
"./.vector_store",
"--embed",
"all-mpnet-base-v2"
]
}
}
}
```
**With re-ranking enabled**:
```json
{
"mcpServers": {
"local-faiss-mcp": {
"command": "local-faiss-mcp",
"args": [
"--index-dir",
"./.vector_store",
"--rerank"
]
}
}
}
```
**Full configuration with embedding and re-ranking**:
```json
{
"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):
```json
{
"mcpServers": {
"local-faiss-mcp": {
"command": "local-faiss-mcp",
"args": [
"--index-dir",
"./.vector_store"
]
}
}
}
```
**Alternative: Using Python module** (if the command isn't in PATH):
```json
{
"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:
```json
{
"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:
| Model | Dimensions | Speed | Quality | Use Case |
|-------|-----------|-------|---------|----------|
| `all-MiniLM-L6-v2` | 384 | Fast | Good | Default, balanced performance |
| `all-mpnet-base-v2` | 768 | Medium | Better | Higher quality embeddings |
| `paraphrase-multilingual-MiniLM-L12-v2` | 384 | Fast | Good | Multilingual support |
| `all-MiniLM-L12-v2` | 384 | Medium | Better | Better quality at same size |
**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:
```bash
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:
```bash
pytest tests/ -v
```
Run specific test files:
```bash
# 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