Compendium
Allows searching and reading local .txt, .pdf, and .docx documents; file-backed sources are read-only.
Allows searching and reading a folder of Markdown notes, with support for tags, wikilinks/backlinks, and optional additive writes.
Supports Obsidian-style Markdown vaults, enabling search and reading of notes with tags and wikilinks/backlinks, plus optional additive writes when enabled.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Compendium
One MCP server for all your personal knowledge: notes, documents, and data.
Point it at a Markdown vault, a folder of PDFs, a CSV, or all three, and an AI assistant can search across them, read what it finds, and cite where it came from. The server runs locally, makes no network calls of its own, and only reads unless you say otherwise. Content the assistant reads is passed to your AI client as usual, so point it only at data you are comfortable sharing with that provider.
"What did I decide about hosting, and is there a book I noted about it?" The assistant searches
notes,docs, andbooksin one call and citesnotes:projects/website.mdandbooks:library.csv#4.
Sources
Type | What it serves | Extras |
| A folder of | tags, |
|
| PDF/DOCX need |
| Every row of a CSV (or folder of CSVs) is an item |
|
Adding another kind of source (a database, an issue tracker, an email archive) means implementing one small class. See Adding a source.
Related MCP server: mor
Tools
The tool set is small and the same whatever sources you configure. Results carry a ref like source:id.
Tool | Purpose |
| Configured sources, their types and capabilities |
| Ranked search across all sources (or one), with snippets |
| Browse by source, tag, or folder, newest first |
| Full content of an item by |
| Items that link to this one (only offered if a source supports links) |
| Additive writes (only offered if a source is writable) |
Items are also available as resources (compendium://notes/projects/web.md), and a weekly_review prompt guides the assistant through summarising recent changes.
Install
Requires Python 3.11+.
git clone https://github.com/vfuoglio/compendium && cd compendium
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"Quick start on one folder (read-only; add --writable to allow create_item / append_to_item):
compendium --dir ~/notesOr describe several sources in a compendium.toml (full example):
[sources.notes]
type = "markdown"
path = "~/notes"
read_only = false # sources are read-only unless you opt in
[sources.docs]
type = "files"
path = "~/Documents/reference"
[sources.books]
type = "csv"
path = "~/data/books.csv"
title_column = "title"Config is found via --config, $COMPENDIUM_CONFIG, ./compendium.toml, or ~/.config/compendium/config.toml. Try the bundled example with the MCP inspector (with your venv activated so compendium is on the PATH):
npx @modelcontextprotocol/inspector compendium --config example/compendium.tomlClaude Code
claude mcp add compendium -- /path/to/compendium/.venv/bin/compendium --config /path/to/compendium.tomlClaude Desktop
{
"mcpServers": {
"compendium": {
"command": "/path/to/compendium/.venv/bin/compendium",
"args": ["--config", "/path/to/compendium.toml"]
}
}
}Design decisions
Sources are plugins behind one interface.
core.Sourcedefineslist,read, andsearch; links and writes are optional capabilities a source opts into. AHubmerges sources and handlessource:idreferences, so the tools never change as you add sources, and the model's tool list stays small.Tools adapt to what's configured. If nothing is writable, the write tools are not offered at all, rather than offered and refused. The server instructions list the actual sources and their access levels.
Read-only by default. Writes need an explicit
read_only = false, and even then they are additive: no delete, overwrite, or edit tool exists. Tools carry MCP annotations (readOnlyHint,destructiveHint: false) so clients can show accurate permission prompts.Safe by construction. File-backed sources resolve every path against their root and reject
.., absolute paths, symlinks pointing outside, hidden folders (.git,.obsidian), and unexpected file types. Escaping symlinks are also hidden from listings and search. Each case has a test.Errors the model can act on. Expected failures (not found, read-only, unknown source) come back as tool errors with a clear message, so the assistant can correct itself. Unexpected crashes stay generic and never leak internals.
Strict config. Typos in option names, bad source names, unknown types, and missing folders fail at startup with a specific message, not silently at query time.
No index to maintain. Search scans sources on each call, with text and table caches keyed on modification time so PDFs and CSVs are parsed once. That is fast for personal-scale data and can never be stale.
One scoring function for every source. Title and tag matches weigh more, and matching more of the query's terms beats repeating one term, so results from different sources can be ranked against each other.
Adding a source
Subclass Source, implement three methods, and register it:
# src/compendium_mcp/sources/mysource.py
from ..core import Hit, Item, Source, query_terms, score_text
class MySource(Source):
type_name = "mysource"
@classmethod
def from_config(cls, name, cfg, base):
return cls(name)
def list(self, tag=None, folder=None) -> list[Item]: ...
def read(self, item_id: str) -> str: ...
def search(self, terms: list[str], limit: int) -> list[Hit]: ...Add it to SOURCE_TYPES in sources/__init__.py, and type = "mysource" works in the config. Set supports_links / supports_write and override links / create / append to opt into those capabilities.
Tests
pip install -e ".[dev]"
pytestThe tests cover each source, ranking, path safety, read-only enforcement, config validation, and a real MCP client talking to the server in-process (tool lists, annotations, error reporting, resources, prompt).
Limitations
Keyword search only, with no semantic ranking. Pair it with an embedding index (see DocTalk) for meaning-based search.
Scans per query: fine for thousands of items, slow for hundreds of thousands.
stdio transport only; a remote HTTP deployment would need authentication added first.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Personal context for every AI: search, read, and write back to your private Markdown library.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Markdown notes in folders, with files, that your AI assistant can read, write and organise.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to search, read, and traverse Markdown note vaults (Obsidian-compatible) with full-text search, backlinks, knowledge graphs, and a persistent memory system for cross-session context.164 npm4MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to search, read, create, update, and remove personal markdown notes stored locally, providing persistent memory across sessions.16 npm2MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with a local folder of Markdown notes, supporting listing, reading, searching, creating, and appending to notes with strict security boundaries.5MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to read, create, update, delete, and search markdown notes stored locally.-