SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI officelocal_faiss_mcp

local_faiss_mcp

Local FAISS vector database for RAG with document ingestion (PDF, TXT, MD, DOCX), semantic search, re-ranking and CLI tools for indexing and querying.

Open website

About this tool

Purpose

local_faiss_mcp aims to provide local vector database functionality for RAG applications, and can be integrated as an MCP server with AI agents such as Claude and Copilot to enable semantic search and memory storage for documents. It is suitable for vector retrieval scenarios that require localization and no external dependencies.

Main Capabilities

  • Local vector storage: Uses FAISS for efficient similarity search, with no external dependencies.
  • Document ingestion: Automatically chunks and embeds documents for storage.
  • Semantic search: Query documents in natural language using sentence embeddings.
  • Persistent storage: Indexes and metadata are saved to disk.
  • MCP compatible: Can be used with any AI agent or client that supports MCP.
  • Command-line tool: v0.2.0 introduces local-faiss command, supporting standalone indexing and search.
  • Document formats: Native support for PDF, TXT, MD; support for DOCX, HTML, EPUB and 40+ other formats via pandoc.
  • Reranking: Two-stage retrieval with reranking to improve result quality.
  • Custom embeddings: Can choose any Hugging Face embedding model.
  • MCP prompts: Built-in prompts for answer extraction and summarization.

Usage

Installation

Installing from PyPI is recommended:

pip install local-faiss-mcp

Upgrade:

pip install --upgrade local-faiss-mcp

Optional extended format support: install pandoc (macOS: brew install pandoc；Linux: apt install pandoc).

Running the server

  1. Use the installed command:local-faiss-mcp(specific commands need to be checked)
  2. Run as a Python module:python -m local_faiss_mcp
  3. Development/testing: run the script directly

Command-line arguments:

  • --index-dir: Directory for storing the FAISS index and metadata (defaults to the current directory)
  • --embed: Hugging Face embedding model name (default all-MiniLM-L6-v2）
  • --rerank: Enable reranking and specify the cross-encoder model (default BAAI/bge-reranker-base)

Available tools

  • ingest_document: Ingest documents into the vector store. Parameters:document(required, text content or file path),source(optional, document source identifier, default "unknown"). Automatically detects file paths and parses them.
  • query_rag_store: Query the vector store to retrieve relevant document chunks. Parameters:query(required, search query text),top_k(optional, number of results to return, default 3).

Available prompts

  • extract-answer: Extract the most relevant answer from retrieved document chunks and attach citations. Parameters:query、chunks(JSON array, containing text、source、distance fields).
  • summarize: Create a focused summary from multiple document chunks. Parameters:topic、chunks、max_length(optional, default 200 words).

Command-line interface

local-faiss CLI provides standalone document indexing and search:

  • Index documents:local-faiss index <路径>(supports glob patterns and recursive folders)
  • Search:local-faiss search <查询>
  • Configuration is automatically read from ./.mcp.json、~/.claude/.mcp.json or ~/.mcp.json , and if absent, a default configuration is created.
  • Incremental indexing, does not overwrite existing indexes, and shows progress.

MCP client configuration

Add the server configuration in Claude Code's .mcp.json . Supports user-level and project-level configuration, and allows customization of the index directory, embedding model, and reranking.

Technical details

  • Embedding model: Default all-MiniLM-L6-v2(384 dimensions), supports any Hugging Face sentence-transformers model, automatically detects dimensions, and persists model selection together with the index.
  • Index type: FAISS IndexFlatL2, exact L2 distance search.
  • Chunking: documents are split into chunks of about 500 words, with an overlap of 50 words.
  • Storage: the index is saved as faiss.index, and metadata is saved as metadata.json.

Use cases

  • Provide local document memory and semantic search for AI agents.
  • Build a RAG question-answering system based on local documents.
  • Vector retrieval applications that require no external dependencies and privacy protection.

Limitations

  • Dependencies must be installed and configured by yourself (such as pandoc for extended formats).
  • After the index is created, the same embedding model must be used; otherwise, a dimension mismatch warning will occur.
  • Other limitations are not yet provided.

Related tools

Browse category