Skip to main content
Glama
jameslovespancakes

vectorise-mcp

by jameslovespancakes
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

vectorise-mcp

Local MCP server that turns folders of documents into a hybrid vector + keyword index that Claude Desktop can search. Stays offline after first model download.

PyPI

Stack

Related MCP server: local-document-rag-agent

Install

pip install vectorise-mcp                 # core
pip install "vectorise-mcp[ocr]"          # + OCR for scanned PDFs / images
pip install "vectorise-mcp[notify]"       # + desktop toast on job completion
pip install "vectorise-mcp[ocr,notify]"   # everything

vectorise-mcp setup                       # pre-download models (~250MB)

Python ≥ 3.10.

Wire into Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "vectorise": {
      "command": "vectorise-mcp",
      "args": ["serve"]
    }
  }
}

Config file location:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop.

File support

Format

Notes

.pdf

text + OCR fallback for scanned pages

.docx, .pptx, .xlsx, .xlsm, .xls

full content + tables

.txt, .md, .markdown

UTF-8

.png, .jpg, .jpeg, .tiff, .bmp, .webp

OCR (requires [ocr])

.doc, .ppt

detected, skipped, reported

Tools exposed to Claude

Tool

What it does

vectorise_list_projects

list all indexed projects

vectorise_index_project(folder, project, mode)

start indexing job, returns job_id instantly

vectorise_reindex_project(project)

SHA1-incremental rescan of all sources

vectorise_index_status(job_id)

instant job snapshot incl. progress + ETA

vectorise_await_index(job_id, timeout_sec)

optional blocking wait

vectorise_list_jobs(active_only)

jobs from current server session

vectorise_search(project, query, k, candidate_pool, file_glob, subdirectory, page_min, page_max, min_similarity)

hybrid + reranked search

vectorise_delete_project(project)

delete project's .db

mode for vectorise_index_project: auto (default — incremental if path already indexed, error on conflict) / replace / append / fail.

Architecture

Indexing job runs in a daemon thread with its own asyncio loop. The MCP server's main loop stays free to serve index_status / search calls regardless of how heavy the embedding/OCR work is. Status calls are instant; search works on the partial index while a job is running.

folder
  ↓  parsers.parse                        (.pdf .docx .pptx .xlsx ...)
chunks (sentence-aware, 384 tok / 96 overlap, single-sentence hard-split)
  ↓  embedder.embed_passages              (BGE-small)
sqlite-vec   +   FTS5 (BM25)              ← per-file SHA1 dedup, basename collision auto-rename
  ↓  search                               (vector top-N + BM25 top-N)
RRF fusion → cross-encoder rerank → top-K

Project DBs live in ~/.vectorise-mcp/<name>.db. Self-contained — source folder can be deleted after indexing.

Config (env vars)

Var

Default

Purpose

VECTORISE_MCP_EMBED_MODEL

BAAI/bge-small-en-v1.5

must be 384-dim

VECTORISE_MCP_RERANKER_MODEL

BAAI/bge-reranker-base

VECTORISE_MCP_EMBED_BATCH

32

VECTORISE_MCP_RERANKER_BATCH

16

VECTORISE_MCP_OCR_MIN_CONFIDENCE

0.5

drop OCR lines below

VECTORISE_MCP_OCR_WORKERS

4

parallel page OCR threads

VECTORISE_MCP_OCR_DPI

200

PDF rasterisation DPI

VECTORISE_MCP_OCR_MAX_DIM

4000

downscale huge images before OCR

VECTORISE_MCP_NOTIFY

1

desktop toast on/off

Performance

CPU

GPU

Indexing throughput

~80 chunks/sec

5–10× faster

Search latency (k=5, ≤500K chunks)

~150ms

similar

Disk per chunk

~2 KB

Cold start

~5s (lazy model load)

Local dev

git clone https://github.com/jameslovespancakes/Vectorised-Embedding-MCP
cd Vectorised-Embedding-MCP
pip install -e ".[ocr,notify]"

# tests bypass MCP transport, drive indexer + tools directly
python tests/smoke_test.py
python tests/smoke_test_projects.py
python tests/smoke_test_jobs.py
python tests/smoke_test_filters.py
python tests/smoke_test_office.py
python tests/smoke_test_chunking.py
python tests/smoke_test_legacy_skip.py

License

MIT.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Data Server

    hkonda015
    A
    license
    Not graded
    quality
    D
    maintenance
    Indexes local files (PDF, TXT, CSV, Markdown) with embeddings for semantic search. Provides both CLI and MCP server interfaces so Claude Desktop can search and read your local documents.
    MIT

  • docsonar

    ribhav-jain
    A
    license
    A
    quality
    B
    maintenance
    A local document search MCP server that indexes folders and provides hybrid keyword+semantic search, enabling users to chat with their documents via MCP clients like Claude Desktop or Claude Code.
    8
    MIT