Markdown Vault MCP server

by pvliesdonk·io.github.pvliesdonk/markdown-vault-mcp·v4.2.0

No reviews yet

Generic markdown vault MCP with hybrid search

B83/100grade B

Write a review Install

What users say

No reviews yet

Be the first

Safety scan

B83/100

full report

Adoption

Growing

33 stars

Reviews

Write one

Nobody has reviewed Markdown Vault MCP yet.

If you have run it, two minutes of your experience saves the next person an afternoon.

Markdown Vault MCP tools (44, 2 write)

write = sends, deletes, buys or posts

Read from the package source without running it. The installed server may list more.

append
Append text to the end of an existing .md note without reading it.
browse_vault
Open a visual vault explorer UI for the user — not for reading vault content.
deco
deletewrite action
Permanently delete a document or attachment.
edit
embeddings_status
Check embedding provider and vector-index status.
fetch
get_backlinks
get_broken_links
Find all links that point to non-existent documents (broken links).
get_connection_path
Find the shortest connection path between two notes in the link graph.
get_context
get_conventions
Get the user's authoring conventions that apply to a note or folder.
get_diff
get_history
List commits that touched a note, folder, or the whole vault.
get_index_status
Report FTS index readiness, progress, and last build error.
get_most_linked
Return the documents with the most inbound links, ranked by backlink count.
get_orphan_notes
Return all notes with no inbound or outbound links.
get_outlinks
Find all links FROM the given document to other documents (outlinks).
get_recent
Get the most recently modified notes in the vault.
get_similar
get_toc
Heading outline for a single note or a whole folder subtree.
git_sync
list_documents
list_folders
List all folder paths that contain documents.
list_tags
List all distinct values for a frontmatter field across the vault.
move_folder
Move an entire folder subtree to a new location in one call, rewriting every link across the vault that points into the moved subtree — the folder-level analogue of 'rename'.
okf_convert_links
Rewrite wikilinks as OKF bundle-root-absolute markdown links.
okf_generate_index
Generate a reserved OKF index.md listing from the table of contents.
okf_seed_log
Seed a reserved OKF log.md change history from git history.
okf_validate
Audit the vault's Open Knowledge Format conformance.
okf_verify
Attest a note as human-reviewed by appending an OKF verification.
read
register
Register the summarize tool on *mcp* as a dual-mode long-running tool.
rename
Rename or move a document or attachment. When renaming a .md note, always pass update_links=True to rewrite links in other documents that point to the old path.
search
show_context
Open a visual context card UI for the user — not for reading note relationships.
stats
vault_context
Return the full NoteContext for a note (app-only).
vault_graph_hubs
Return the most-linked notes and their connections as a graph (app-only).
vault_graph_neighborhood
Return the link neighborhood of a note as a node/edge graph (app-only).
vault_list
List folders and notes in a vault directory (app-only).
vault_read
Read a note's full content for preview rendering (app-only).
vault_search
Search the vault (app-only).
writewrite action

Public scan report

scanner v0.1.5 · 2026-09-19 · same rubric, same numbers if you re-run it

no findings

Code scan124 source files scanned25/25
–Live reliabilityno gateway calls yet and no remote to proben/a
–Tool poisoningtools not inspected (local package is not executed); not countedn/a
Auth qualitystatic API keys via environment variables6/15
Maintenancelast push 0 days ago15/15
Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Overall 83/100. Components that don't apply are left out of the denominator. Any critical finding is an F.Rubric Appeal a finding JSON

Install directly

claude mcp add markdown-vault-mcp -- uvx markdown-vault-mcp

Add to Cursor

Markdown Vault MCP: common questions

Is Markdown Vault MCP server safe?: Mostly: it is graded B (83/100). Read the Markdown Vault MCP safety report
How do I install Markdown Vault MCP?: It runs on your machine. Copy the Claude Code, Claude Desktop or Cursor config from the install section.
Does Markdown Vault MCP need an API key?: Yes. The registry entry asks for OPENAI_API_KEY, VOYAGE_API_KEY, MARKDOWN_VAULT_MCP_GIT_TOKEN, MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET and 6 more.
Is Markdown Vault MCP maintained?: The last commit was in the last day (2026-09-19). The latest release is v4.2.0.
What can I use instead of Markdown Vault MCP?: Servers from other publishers that do the same job: DocsMint MCP server, M3 Memory MCP server and Stackexchange MCP server. Compare all Markdown Vault MCP alternatives.

Alternatives to Markdown Vault MCP

Same job from other publishers: the closest match first, then the best rated.

All Markdown Vault MCP alternatives →

DocsMint
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
not reviewed
Established
A
M3 Memory
Local-first memory — 100+ tools, 99.2% LongMemEval-S retrieval@10, hybrid search, GDPR, no cloud.
not reviewed
Established
A
Stackexchange
Search Stack Exchange questions, fetch Q&A threads as markdown, look up tag FAQs and user profiles.
not reviewed
Growing
A
Neuromcp
Semantic memory for AI agents with hybrid search, knowledge graph, and consolidation
not reviewed
Growing
B

Markdown Vault MCP vs DocsMint Markdown Vault MCP vs M3 Memory Markdown Vault MCP vs Stackexchange

Run it through the gateway

Local package. It runs on your machine, not through the gateway.

Rating: —
Safety grade: B · 83/100
Stars: 33
Downloads/wk: –
Price: Free
Licence: MIT
Transport: Local · mixed
Version: 4.2.0
Category: Web search
Last release: 2026-09-19

Credentials it needs

MARKDOWN_VAULT_MCP_KV_STORE_URLPersistent-state backend URL shared by every pvl-core subsystem that needs state. `memory://` is in-process and lost on restart; `file:///path` persists on one server; `redis://`, `dynamodb://` and `mongodb://` each need their matching extra. When unset, defaults to `file:///data/state` (the volume family Docker images mount), or to `memory://` (with a warning) on a host where that directory is not usable.
MARKDOWN_VAULT_MCP_TOOLS_ALLOWComma-separated explicit tool names this instance exposes; every other tool is hidden from listings and cannot be invoked. Names matching no registered tool are inert. Mutually exclusive with `tools_deny`. Takes effect through `apply_tool_visibility`.
MARKDOWN_VAULT_MCP_TOOLS_DENYComma-separated explicit tool names hidden from this instance (absent from listings, cannot be invoked). Names matching no registered tool are inert. Mutually exclusive with `tools_allow`. Takes effect through `apply_tool_visibility`.
MARKDOWN_VAULT_MCP_SERVER_NAMERename this server instance; defaults to the project name.
MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTIONConcise routing context that distinguishes this deployment's material or responsibility.
MARKDOWN_VAULT_MCP_INSTRUCTIONS_EXTRADeployment-specific behavioral policy added to the generated MCP instructions.
MARKDOWN_VAULT_MCP_INSTRUCTIONSLegacy: replaces all generated MCP instructions (deprecated; use _INSTANCE_DESCRIPTION for routing and _INSTRUCTIONS_EXTRA for policy).
FASTMCP_LOG_LEVELLog level for FastMCP internals and app loggers (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG.
FASTMCP_ENABLE_RICH_LOGGINGSet false for plain or structured JSON log output.
OLLAMA_HOSTOllama server URL for the ollama embedding provider. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the Ollama ecosystem convention.
OPENAI_API_KEYsecretOpenAI API key for the openai embedding provider, and the fallback key for the summarize tool when MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY is unset. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the OpenAI ecosystem convention.
VOYAGE_API_KEYsecretVoyage AI API key for the voyage embedding provider. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the OPENAI_API_KEY / OLLAMA_HOST convention. Setting it never auto-selects the provider; choose it explicitly with MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER=voyage.
OPENAI_BASE_URLBare fallback for MARKDOWN_VAULT_MCP_OPENAI_BASE_URL (embeddings). For the summarize tool it only routes traffic when an API key already enables the feature; it never enables summarize by itself.
OPENAI_EMBEDDING_MODELBare fallback for MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODEL.
MARKDOWN_VAULT_MCP_BUILD_TIMEOUT_SMaximum seconds an index-backed tool or resource waits for the FTS index to become queryable during a cold-start background build before raising IndexUnavailableError(reason="timeout"). Increase for large vaults.
MARKDOWN_VAULT_MCP_DRAIN_TIMEOUT_SMaximum seconds an index-querying read tool waits for the IndexWriter to drain when called with wait_for_pending_writes=true. On timeout the tool answers from the current index and reports index_stale=true in the response _meta.
MARKDOWN_VAULT_MCP_SOURCE_DIRPath to the markdown vault directory. Required — the server refuses to start without it. Symbolic links inside the vault are followed on Python 3.13+.
MARKDOWN_VAULT_MCP_READ_ONLYSet to true to hide the write tools (write, edit, append, delete, rename, move_folder, fetch, git_sync, the okf_* tools, create_upload_link) and serve a search-only vault. git_sync also needs managed git mode; create_upload_link needs an HTTP transport.
MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTINGSet to true to refuse a write that would overwrite an existing file when no if_match etag is supplied. Deliberate replacement still works: read the file first, then pass if_match. Unaffected: edit, append, delete, rename.
MARKDOWN_VAULT_MCP_DISABLE_APPS_UIHide the MCP Apps UI tools (browse_vault, show_context) from the tool listing for clients that do not render MCP Apps panels.
MARKDOWN_VAULT_MCP_INDEX_PATHPath to the SQLite FTS5 index file; unset keeps the index in memory. Set it for persistence across restarts.
MARKDOWN_VAULT_MCP_STATE_PATHPath to the change-tracking state file. Defaults to {SOURCE_DIR}/.markdown_vault_mcp/state.json.
MARKDOWN_VAULT_MCP_EMBEDDINGS_PATHPath to the numpy embeddings file; required to enable semantic search.
MARKDOWN_VAULT_MCP_INDEXED_FIELDSComma-separated frontmatter fields promoted to the tag index for structured filtering. Changing it cold-rebuilds the index once on next startup; SEARCHABLE_FIELDS inherits this value when unset.
MARKDOWN_VAULT_MCP_REQUIRED_FIELDSComma-separated frontmatter fields required on every document; documents missing any are excluded from the index.
MARKDOWN_VAULT_MCP_EXCLUDEComma-separated glob patterns excluded from scanning, e.g. .obsidian/**,.trash/**.
MARKDOWN_VAULT_MCP_TITLE_FIELDFrontmatter field used as the document title (falls back to title, the first H1, then the filename). Changing it cold-rebuilds the index once on next startup.
MARKDOWN_VAULT_MCP_SEARCHABLE_FIELDSComma-separated frontmatter fields whose text values become keyword-searchable and enrich first-chunk embeddings. Inherits INDEXED_FIELDS when unset; the sentinel none means filterable but not searchable. Changing it cold-rebuilds the index and re-embeds once on next startup.
MARKDOWN_VAULT_MCP_TEMPLATES_FOLDERRelative folder where note templates live (used by the create_from_template prompt).
MARKDOWN_VAULT_MCP_PROMPTS_FOLDERDirectory of .md prompt files that extend or override built-in prompts; a relative path is resolved against SOURCE_DIR.
MARKDOWN_VAULT_MCP_CONVENTIONS_FILEFilename of the per-folder conventions files surfaced to clients at write time (bare .md filename without glob characters). Set to none to disable folder conventions.
MARKDOWN_VAULT_MCP_OKF_MODEOKF (Open Knowledge Format) read semantics. With auto (the default), read annotations switch on when the vault declares an OKF version in its root index.md. Use off to disable OKF semantics entirely, or on to force them for an undeclared vault. Annotations are read-only; write behavior is never affected.
MARKDOWN_VAULT_MCP_OKF_WRITEOKF (Open Knowledge Format) enforced write layer. When true on an OKF-active vault, the server stamps generated provenance on each write and clears any verified attestation when a note's content changes. It also keeps each written folder's log.md and index.md current, and exposes the okf_verify tool. Requires OKF_MODE to be auto or on (a true value with OKF_MODE=off is a config error). Off by default.
MARKDOWN_VAULT_MCP_OKF_VERIFYHow the okf_verify tool attributes a human review. This applies only when OKF_WRITE is on, which gates the tool. With elicit (the default), okf_verify asks the human to confirm the review through an MCP elicitation, then records the attestation only on an affirmative reply. It fails closed when the client cannot elicit or the human declines, so a model holding the human's token cannot self-attest. Set trust-auth instead to attribute to the authenticated caller with no confirmation, which is safe only when the sole caller is a human-driven UI. Set off to hide the tool, leaving attestation to external tooling. A non-default value with OKF_WRITE off is a config error.
MARKDOWN_VAULT_MCP_ATTACHMENT_EXTENSIONSComma-separated allowed attachment extensions (e.g. pdf,png,jpg); case and a leading dot are ignored, so PDF and .pdf name the same type. Use * to allow every non-markdown file. Unset selects the built-in allowlist. A link whose target has a listed extension is not part of the link graph; changing the list rebuilds the index once.
MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MBMaximum attachment size in MB returned by read / accepted by write; 0 disables the limit.
MARKDOWN_VAULT_MCP_MAX_NOTE_READ_BYTESMaximum bytes returned by a full-document read of a note; use `read(path, section=…)` for partial reads. 0 disables the limit.
MARKDOWN_VAULT_MCP_DEFAULT_SEARCH_MODEMode used when a search call omits 'mode': auto, keyword, semantic, or hybrid. The default 'auto' picks hybrid when embeddings are configured and keyword when they are not. Pin 'keyword' to keep unqualified searches off the embedding provider (each hybrid or semantic search embeds the query, which costs an API call on a metered provider). A configured semantic/hybrid default also degrades to keyword without embeddings, so no setting can make a vault unsearchable; an explicit mode= argument is never downgraded.
MARKDOWN_VAULT_MCP_CHUNKS_PER_FILEMaximum chunks returned per document in search results.
MARKDOWN_VAULT_MCP_SNIPPET_WORDSWidth of the snippet window (words) in search results; 0 returns full chunk content.
MARKDOWN_VAULT_MCP_LENGTH_DOWNWEIGHT_ALPHADown-weights longer chunks in ranking: score / (1 + alpha * log(chunk_count)).
MARKDOWN_VAULT_MCP_MAX_CHUNK_WORDSWord cap per chunk; the adaptive chunker splits at deeper heading levels, then paragraph/word boundaries, to respect it. Match it to the embedding model's context. A reindex applies a new value.
MARKDOWN_VAULT_MCP_MAX_CHUNK_CHARSCharacter cap enforced alongside MAX_CHUNK_WORDS to bound token-dense chunks. Unset derives min(1500, model context * 2.8). Set a positive value for an exact cap, or -1 to scale with the model's full context (can exhaust memory on long-context models). A reindex applies a new value.
MARKDOWN_VAULT_MCP_CHUNK_OVERLAP_WORDSWords of overlap between adjacent budget-split fragments of the same heading section (0 disables). A reindex applies a new value.
MARKDOWN_VAULT_MCP_FOLDER_WEIGHTSFolder-prefix score multipliers (`prefix:weight` pairs, comma-separated, weights > 0) applied to all search modes; the deepest matching prefix wins (sessions:0.5 demotes sessions/**).
MARKDOWN_VAULT_MCP_FTS_WEIGHTSPer-column BM25 weights (`column:weight` pairs, comma-separated, weights >= 0) for keyword ranking. Columns: path, title, folder, heading, content, summary.
MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDEREmbedding provider: openai, voyage, ollama, or fastembed. Unset auto-detects from the environment (never voyage). Any OpenAI-compatible endpoint works with openai plus OPENAI_BASE_URL; see the embeddings guide.
MARKDOWN_VAULT_MCP_OLLAMA_MODELOllama embedding model name.
MARKDOWN_VAULT_MCP_OLLAMA_CPU_ONLYForce Ollama to embed on CPU only.
MARKDOWN_VAULT_MCP_VOYAGE_MODELVoyage AI embedding model name.
MARKDOWN_VAULT_MCP_OPENAI_BASE_URLOpenAI-compatible API base URL for embeddings; the bare OPENAI_BASE_URL is honoured as a fallback.
MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODELOpenAI-compatible embedding model name; the bare OPENAI_EMBEDDING_MODEL is honoured as a fallback.
MARKDOWN_VAULT_MCP_FASTEMBED_MODELFastEmbed model name.
MARKDOWN_VAULT_MCP_FASTEMBED_CACHE_DIRFastEmbed model cache directory (in Docker, stored under /data/state/fastembed).
MARKDOWN_VAULT_MCP_EMBED_CONTEXTEnrich embedding input with the note title, chunk heading, and (first chunk) searchable-field values. Flipping it re-embeds the whole vault once on next startup.
MARKDOWN_VAULT_MCP_EMBED_TIMEOUT_SPer-request wall-clock budget in seconds for a single embedding HTTP call (OpenAI/Ollama). The local FastEmbed backend runs in-process with no network call and ignores this. CPU-only or large-model workloads may need 60-120 s; raise this if batches time out.
MARKDOWN_VAULT_MCP_EMBEDDING_BATCH_SIZENumber of chunks sent per embedding request. Smaller batches shorten each request (useful under a tight timeout on slow models) at the cost of more round-trips.
MARKDOWN_VAULT_MCP_GIT_TOKENsecretToken/password for HTTPS git auth; remotes must be HTTPS when set.
MARKDOWN_VAULT_MCP_GIT_REPO_URLHTTPS remote URL for managed git mode: the server clones into an empty SOURCE_DIR on startup (or validates an existing origin) and enables the pull loop, auto-commit, and deferred push.
MARKDOWN_VAULT_MCP_GIT_USERNAMEUsername for HTTPS git auth prompts (x-access-token for GitHub, oauth2 for GitLab, the account name for Bitbucket).
MARKDOWN_VAULT_MCP_GIT_PULL_INTERVAL_SSeconds between git fetch + fast-forward update attempts; 0 disables periodic pull.
MARKDOWN_VAULT_MCP_GIT_PUSH_DELAY_SSeconds of write-idle time before pushing; 0 pushes only on shutdown.
MARKDOWN_VAULT_MCP_GIT_COMMIT_NAMEGit committer name for auto-commits; set this in Docker where git config user.name is empty.
MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAILGit committer email for auto-commits.
MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME_CLAIMOIDC claim key used as the commit author name (e.g. name); overrides GIT_COMMIT_NAME per request when an OIDC token is present. The claim is resolved when the tool call arrives and carried to the background commit, so it applies on every write. A configured claim the token does not carry is reported once at WARNING and the static identity is used.
MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL_CLAIMOIDC claim key used as the commit author email (e.g. email); overrides GIT_COMMIT_EMAIL per request when an OIDC token is present. Resolved and carried the same way as the name claim.
MARKDOWN_VAULT_MCP_GIT_LFSRun git lfs pull on startup to fetch LFS-tracked attachments; set to false for repos without LFS.
MARKDOWN_VAULT_MCP_FILE_WATCHERWatch the vault for external filesystem changes; auto-disabled when git pull is active or a webhook can deliver (HTTP/SSE transports only). Requires the file-watcher extra.
MARKDOWN_VAULT_MCP_FILE_WATCHER_DEBOUNCE_SSeconds of quiet after the last filesystem event before reindexing.
MARKDOWN_VAULT_MCP_FILE_WATCHER_ROOT_FLOORKeep the non-recursive watch on the vault root; set false to register zero source-dir-rooted FSEvents streams (avoids repeated macOS access prompts on a home-rooted vault) at the cost of root-level files relying on scans.
MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRETsecretShared secret for the GitHub push-event webhook; when set, mounts POST /github-webhook on HTTP/SSE transports to trigger an immediate pull + reindex on push events.
MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SIGNING_TOKENsecretSigning token for the GitLab push-event webhook (GitLab 19.0+); when set, mounts POST /gitlab-webhook on HTTP/SSE transports to trigger an immediate pull + reindex on push events. GitLab generates this value; copy the `whsec_` token it shows under Generate signing token rather than inventing one. Deliveries are authenticated by HMAC-SHA256 over the webhook id, timestamp and body, and a delivery older than 5 minutes is rejected.
MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SECRET_TOKENsecretSecret token for the GitLab push-event webhook, GitLab's plain-text form and the only one below 19.0; also mounts POST /gitlab-webhook. It proves nothing about the body and cannot expire, so prefer the signing token where the GitLab version offers it. Setting both accepts either, which is how an existing webhook migrates.
MARKDOWN_VAULT_MCP_SUMMARIZE_PROVIDERSummarization backend (only openai is recognised). Unset auto-detects: the backend activates when credentials or an explicit endpoint are present.
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEYsecretAPI key for the OpenAI-compatible summarize endpoint; the bare OPENAI_API_KEY is honoured as a fallback. Unset works for keyless local endpoints (Ollama).
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_BASE_URLOpenAI-compatible endpoint base URL for the summarize tool; setting it enables the tool even without an API key. The bare OPENAI_BASE_URL routes traffic only when a key already enables the feature.
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_MODELChat model id used for summaries.
MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_TOKENSUpper bound on generated tokens per summarize call; on reasoning models this budget also covers internal reasoning tokens.
MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_NOTESCap on the number of notes summarised in one call (subtree expansion truncates to this many).
MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_INPUT_CHARSAggregate cap on note characters sent to the model in one call; excess is truncated with a flag on the result.
MARKDOWN_VAULT_MCP_SUMMARIZE_TIMEOUTPer-request wall-clock budget in seconds for a single summarize backend call; keep it below the MCP client's request timeout so the server-side error wins the race.
MARKDOWN_VAULT_MCP_TRANSFER_TTL_DEFAULT_SLink lifetime in seconds when the caller requests no explicit TTL.
MARKDOWN_VAULT_MCP_TRANSFER_TTL_MAX_SCeiling in seconds a caller-requested link TTL is clamped to.
MARKDOWN_VAULT_MCP_TRANSFER_GRACE_TTL_SPost-success grace window in seconds: a served token's TTL shrinks to this so a stalled transfer can retry within it.
MARKDOWN_VAULT_MCP_TRANSFER_LEASE_SCrashed-handler reclaim window in seconds for an in-flight reservation.
MARKDOWN_VAULT_MCP_TRANSFER_MAX_UPLOAD_BYTESMaximum size in bytes of a single upload.
MARKDOWN_VAULT_MCP_JOBS_SOFT_DEADLINE_SSeconds a long-running tool call may run in the foreground before it is promoted to a background job and a job handle is returned instead.
MARKDOWN_VAULT_MCP_JOBS_RESULT_TTL_SSeconds a background-job record (working or finished) is retained for polling before it expires from the store.
MARKDOWN_VAULT_MCP_JOBS_MAX_PER_SUBJECTMaximum live background jobs per calling subject; further promotions are rejected until older records expire.
MARKDOWN_VAULT_MCP_BASE_URLPublic base URL of the deployed server, for example `https://mcp.example.com`. Required for OIDC. Also the fallback source of the MCP Apps domain when `app_domain` is unset.
MARKDOWN_VAULT_MCP_BEARER_TOKENsecretSingle shared bearer token; enables bearer auth unless `bearer_tokens_file` is set, which takes precedence.
MARKDOWN_VAULT_MCP_OIDC_CONFIG_URLOIDC discovery document URL, for example `https://auth.example.com/.well-known/openid-configuration`.
MARKDOWN_VAULT_MCP_OIDC_CLIENT_IDOIDC client identifier registered with the provider.
MARKDOWN_VAULT_MCP_OIDC_CLIENT_SECRETsecretOIDC client secret registered with the provider.
MARKDOWN_VAULT_MCP_OIDC_AUDIENCEExpected `aud` claim; tokens issued for another audience are rejected.
MARKDOWN_VAULT_MCP_OIDC_REQUIRED_SCOPESScopes a caller must present, space- or comma-separated. Defaults to `openid` in oidc-proxy mode.
MARKDOWN_VAULT_MCP_OIDC_ADVERTISED_SCOPESScopes advertised to MCP clients in protected-resource metadata, space- or comma-separated. Overrides the default `openid offline_access`; `oidc_required_scopes` is always added on top. Set this when the registered client is not permitted `offline_access`, or to have clients request extra claim scopes (such as `groups`) without also requiring them in every token.
MARKDOWN_VAULT_MCP_OIDC_JWT_SIGNING_KEYsecretSigning key for issued tokens; used in oidc-proxy mode only. When unset, the key is derived deterministically from `oidc_client_secret`, so tokens survive a restart. Rotating that secret then invalidates every issued token. Set this explicitly to decouple token validity from secret rotation. Generate with `openssl rand -hex 32`.
MARKDOWN_VAULT_MCP_OIDC_VERIFY_ACCESS_TOKENValidate the access token instead of the id token.
MARKDOWN_VAULT_MCP_KV_STORE_URLPersistent-state backend URL shared by every pvl-core subsystem that needs state. `memory://` is in-process and lost on restart; `file:///path` persists on one server; `redis://`, `dynamodb://` and `mongodb://` each need their matching extra. When unset, defaults to `file:///data/state` (the volume family Docker images mount), or to `memory://` (with a warning) on a host where that directory is not usable.
MARKDOWN_VAULT_MCP_APP_DOMAINMCP Apps iframe domain, used for CSP sandboxing. Overrides the host derived from `base_url`.
MARKDOWN_VAULT_MCP_TOOLS_ALLOWComma-separated explicit tool names this instance exposes; every other tool is hidden from listings and cannot be invoked. Names matching no registered tool are inert. Mutually exclusive with `tools_deny`. Takes effect through `apply_tool_visibility`.
MARKDOWN_VAULT_MCP_TOOLS_DENYComma-separated explicit tool names hidden from this instance (absent from listings, cannot be invoked). Names matching no registered tool are inert. Mutually exclusive with `tools_allow`. Takes effect through `apply_tool_visibility`.
MARKDOWN_VAULT_MCP_AUTH_MODEExplicit auth-mode override, accepting `remote` or `oidc-proxy` (case- and whitespace-insensitive). When unset the mode is auto-detected from which auth variables are set; the override exists because having all four OIDC variables set is ambiguous between those two modes. Other values are ignored with a warning.
MARKDOWN_VAULT_MCP_BEARER_TOKENS_FILEPath to a TOML file mapping bearer tokens to subjects; overrides the single-token `bearer_token` mode.
MARKDOWN_VAULT_MCP_BEARER_DEFAULT_SUBJECTSubject assigned to the single-token bearer mode; ignored when `bearer_tokens_file` is set, since mapped mode carries per-token subjects.
MARKDOWN_VAULT_MCP_SERVER_NAMERename this server instance; defaults to the project name.
MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTIONConcise routing context that distinguishes this deployment's material or responsibility.
MARKDOWN_VAULT_MCP_INSTRUCTIONS_EXTRADeployment-specific behavioral policy added to the generated MCP instructions.
MARKDOWN_VAULT_MCP_INSTRUCTIONSLegacy: replaces all generated MCP instructions (deprecated; use _INSTANCE_DESCRIPTION for routing and _INSTRUCTIONS_EXTRA for policy).
MARKDOWN_VAULT_MCP_HTTP_PATHMount path for the MCP endpoint.
PUIDRun the server process as this UID; the container entrypoint reassigns ownership of writable paths to match.
PGIDRun the server process as this GID; pair with PUID to match the owner of a mounted volume.
FASTMCP_LOG_LEVELLog level for FastMCP internals and app loggers (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG.
FASTMCP_ENABLE_RICH_LOGGINGSet false for plain or structured JSON log output.
OLLAMA_HOSTOllama server URL for the ollama embedding provider. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the Ollama ecosystem convention.
OPENAI_API_KEYsecretOpenAI API key for the openai embedding provider, and the fallback key for the summarize tool when MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY is unset. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the OpenAI ecosystem convention.
VOYAGE_API_KEYsecretVoyage AI API key for the voyage embedding provider. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the OPENAI_API_KEY / OLLAMA_HOST convention. Setting it never auto-selects the provider; choose it explicitly with MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER=voyage.
OPENAI_BASE_URLBare fallback for MARKDOWN_VAULT_MCP_OPENAI_BASE_URL (embeddings). For the summarize tool it only routes traffic when an API key already enables the feature; it never enables summarize by itself.
OPENAI_EMBEDDING_MODELBare fallback for MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODEL.
MARKDOWN_VAULT_MCP_BUILD_TIMEOUT_SMaximum seconds an index-backed tool or resource waits for the FTS index to become queryable during a cold-start background build before raising IndexUnavailableError(reason="timeout"). Increase for large vaults.
MARKDOWN_VAULT_MCP_DRAIN_TIMEOUT_SMaximum seconds an index-querying read tool waits for the IndexWriter to drain when called with wait_for_pending_writes=true. On timeout the tool answers from the current index and reports index_stale=true in the response _meta.
MARKDOWN_VAULT_MCP_SOURCE_DIRPath to the markdown vault directory. Required — the server refuses to start without it. Symbolic links inside the vault are followed on Python 3.13+.
MARKDOWN_VAULT_MCP_READ_ONLYSet to true to hide the write tools (write, edit, append, delete, rename, move_folder, fetch, git_sync, the okf_* tools, create_upload_link) and serve a search-only vault. git_sync also needs managed git mode; create_upload_link needs an HTTP transport.
MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTINGSet to true to refuse a write that would overwrite an existing file when no if_match etag is supplied. Deliberate replacement still works: read the file first, then pass if_match. Unaffected: edit, append, delete, rename.
MARKDOWN_VAULT_MCP_DISABLE_APPS_UIHide the MCP Apps UI tools (browse_vault, show_context) from the tool listing for clients that do not render MCP Apps panels.
MARKDOWN_VAULT_MCP_INDEX_PATHPath to the SQLite FTS5 index file; unset keeps the index in memory. Set it for persistence across restarts.
MARKDOWN_VAULT_MCP_STATE_PATHPath to the change-tracking state file. Defaults to {SOURCE_DIR}/.markdown_vault_mcp/state.json.
MARKDOWN_VAULT_MCP_EMBEDDINGS_PATHPath to the numpy embeddings file; required to enable semantic search.
MARKDOWN_VAULT_MCP_INDEXED_FIELDSComma-separated frontmatter fields promoted to the tag index for structured filtering. Changing it cold-rebuilds the index once on next startup; SEARCHABLE_FIELDS inherits this value when unset.
MARKDOWN_VAULT_MCP_REQUIRED_FIELDSComma-separated frontmatter fields required on every document; documents missing any are excluded from the index.
MARKDOWN_VAULT_MCP_EXCLUDEComma-separated glob patterns excluded from scanning, e.g. .obsidian/**,.trash/**.
MARKDOWN_VAULT_MCP_TITLE_FIELDFrontmatter field used as the document title (falls back to title, the first H1, then the filename). Changing it cold-rebuilds the index once on next startup.
MARKDOWN_VAULT_MCP_SEARCHABLE_FIELDSComma-separated frontmatter fields whose text values become keyword-searchable and enrich first-chunk embeddings. Inherits INDEXED_FIELDS when unset; the sentinel none means filterable but not searchable. Changing it cold-rebuilds the index and re-embeds once on next startup.
MARKDOWN_VAULT_MCP_TEMPLATES_FOLDERRelative folder where note templates live (used by the create_from_template prompt).
MARKDOWN_VAULT_MCP_PROMPTS_FOLDERDirectory of .md prompt files that extend or override built-in prompts; a relative path is resolved against SOURCE_DIR.
MARKDOWN_VAULT_MCP_CONVENTIONS_FILEFilename of the per-folder conventions files surfaced to clients at write time (bare .md filename without glob characters). Set to none to disable folder conventions.
MARKDOWN_VAULT_MCP_OKF_MODEOKF (Open Knowledge Format) read semantics. With auto (the default), read annotations switch on when the vault declares an OKF version in its root index.md. Use off to disable OKF semantics entirely, or on to force them for an undeclared vault. Annotations are read-only; write behavior is never affected.
MARKDOWN_VAULT_MCP_OKF_WRITEOKF (Open Knowledge Format) enforced write layer. When true on an OKF-active vault, the server stamps generated provenance on each write and clears any verified attestation when a note's content changes. It also keeps each written folder's log.md and index.md current, and exposes the okf_verify tool. Requires OKF_MODE to be auto or on (a true value with OKF_MODE=off is a config error). Off by default.
MARKDOWN_VAULT_MCP_OKF_VERIFYHow the okf_verify tool attributes a human review. This applies only when OKF_WRITE is on, which gates the tool. With elicit (the default), okf_verify asks the human to confirm the review through an MCP elicitation, then records the attestation only on an affirmative reply. It fails closed when the client cannot elicit or the human declines, so a model holding the human's token cannot self-attest. Set trust-auth instead to attribute to the authenticated caller with no confirmation, which is safe only when the sole caller is a human-driven UI. Set off to hide the tool, leaving attestation to external tooling. A non-default value with OKF_WRITE off is a config error.
MARKDOWN_VAULT_MCP_ATTACHMENT_EXTENSIONSComma-separated allowed attachment extensions (e.g. pdf,png,jpg); case and a leading dot are ignored, so PDF and .pdf name the same type. Use * to allow every non-markdown file. Unset selects the built-in allowlist. A link whose target has a listed extension is not part of the link graph; changing the list rebuilds the index once.
MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MBMaximum attachment size in MB returned by read / accepted by write; 0 disables the limit.
MARKDOWN_VAULT_MCP_MAX_NOTE_READ_BYTESMaximum bytes returned by a full-document read of a note; use `read(path, section=…)` for partial reads. 0 disables the limit.
MARKDOWN_VAULT_MCP_DEFAULT_SEARCH_MODEMode used when a search call omits 'mode': auto, keyword, semantic, or hybrid. The default 'auto' picks hybrid when embeddings are configured and keyword when they are not. Pin 'keyword' to keep unqualified searches off the embedding provider (each hybrid or semantic search embeds the query, which costs an API call on a metered provider). A configured semantic/hybrid default also degrades to keyword without embeddings, so no setting can make a vault unsearchable; an explicit mode= argument is never downgraded.
MARKDOWN_VAULT_MCP_CHUNKS_PER_FILEMaximum chunks returned per document in search results.
MARKDOWN_VAULT_MCP_SNIPPET_WORDSWidth of the snippet window (words) in search results; 0 returns full chunk content.
MARKDOWN_VAULT_MCP_LENGTH_DOWNWEIGHT_ALPHADown-weights longer chunks in ranking: score / (1 + alpha * log(chunk_count)).
MARKDOWN_VAULT_MCP_MAX_CHUNK_WORDSWord cap per chunk; the adaptive chunker splits at deeper heading levels, then paragraph/word boundaries, to respect it. Match it to the embedding model's context. A reindex applies a new value.
MARKDOWN_VAULT_MCP_MAX_CHUNK_CHARSCharacter cap enforced alongside MAX_CHUNK_WORDS to bound token-dense chunks. Unset derives min(1500, model context * 2.8). Set a positive value for an exact cap, or -1 to scale with the model's full context (can exhaust memory on long-context models). A reindex applies a new value.
MARKDOWN_VAULT_MCP_CHUNK_OVERLAP_WORDSWords of overlap between adjacent budget-split fragments of the same heading section (0 disables). A reindex applies a new value.
MARKDOWN_VAULT_MCP_FOLDER_WEIGHTSFolder-prefix score multipliers (`prefix:weight` pairs, comma-separated, weights > 0) applied to all search modes; the deepest matching prefix wins (sessions:0.5 demotes sessions/**).
MARKDOWN_VAULT_MCP_FTS_WEIGHTSPer-column BM25 weights (`column:weight` pairs, comma-separated, weights >= 0) for keyword ranking. Columns: path, title, folder, heading, content, summary.
MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDEREmbedding provider: openai, voyage, ollama, or fastembed. Unset auto-detects from the environment (never voyage). Any OpenAI-compatible endpoint works with openai plus OPENAI_BASE_URL; see the embeddings guide.
MARKDOWN_VAULT_MCP_OLLAMA_MODELOllama embedding model name.
MARKDOWN_VAULT_MCP_OLLAMA_CPU_ONLYForce Ollama to embed on CPU only.
MARKDOWN_VAULT_MCP_VOYAGE_MODELVoyage AI embedding model name.
MARKDOWN_VAULT_MCP_OPENAI_BASE_URLOpenAI-compatible API base URL for embeddings; the bare OPENAI_BASE_URL is honoured as a fallback.
MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODELOpenAI-compatible embedding model name; the bare OPENAI_EMBEDDING_MODEL is honoured as a fallback.
MARKDOWN_VAULT_MCP_FASTEMBED_MODELFastEmbed model name.
MARKDOWN_VAULT_MCP_FASTEMBED_CACHE_DIRFastEmbed model cache directory (in Docker, stored under /data/state/fastembed).
MARKDOWN_VAULT_MCP_EMBED_CONTEXTEnrich embedding input with the note title, chunk heading, and (first chunk) searchable-field values. Flipping it re-embeds the whole vault once on next startup.
MARKDOWN_VAULT_MCP_EMBED_TIMEOUT_SPer-request wall-clock budget in seconds for a single embedding HTTP call (OpenAI/Ollama). The local FastEmbed backend runs in-process with no network call and ignores this. CPU-only or large-model workloads may need 60-120 s; raise this if batches time out.
MARKDOWN_VAULT_MCP_EMBEDDING_BATCH_SIZENumber of chunks sent per embedding request. Smaller batches shorten each request (useful under a tight timeout on slow models) at the cost of more round-trips.
MARKDOWN_VAULT_MCP_GIT_TOKENsecretToken/password for HTTPS git auth; remotes must be HTTPS when set.
MARKDOWN_VAULT_MCP_GIT_REPO_URLHTTPS remote URL for managed git mode: the server clones into an empty SOURCE_DIR on startup (or validates an existing origin) and enables the pull loop, auto-commit, and deferred push.
MARKDOWN_VAULT_MCP_GIT_USERNAMEUsername for HTTPS git auth prompts (x-access-token for GitHub, oauth2 for GitLab, the account name for Bitbucket).
MARKDOWN_VAULT_MCP_GIT_PULL_INTERVAL_SSeconds between git fetch + fast-forward update attempts; 0 disables periodic pull.
MARKDOWN_VAULT_MCP_GIT_PUSH_DELAY_SSeconds of write-idle time before pushing; 0 pushes only on shutdown.
MARKDOWN_VAULT_MCP_GIT_COMMIT_NAMEGit committer name for auto-commits; set this in Docker where git config user.name is empty.
MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAILGit committer email for auto-commits.
MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME_CLAIMOIDC claim key used as the commit author name (e.g. name); overrides GIT_COMMIT_NAME per request when an OIDC token is present. The claim is resolved when the tool call arrives and carried to the background commit, so it applies on every write. A configured claim the token does not carry is reported once at WARNING and the static identity is used.
MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL_CLAIMOIDC claim key used as the commit author email (e.g. email); overrides GIT_COMMIT_EMAIL per request when an OIDC token is present. Resolved and carried the same way as the name claim.
MARKDOWN_VAULT_MCP_GIT_LFSRun git lfs pull on startup to fetch LFS-tracked attachments; set to false for repos without LFS.
MARKDOWN_VAULT_MCP_FILE_WATCHERWatch the vault for external filesystem changes; auto-disabled when git pull is active or a webhook can deliver (HTTP/SSE transports only). Requires the file-watcher extra.
MARKDOWN_VAULT_MCP_FILE_WATCHER_DEBOUNCE_SSeconds of quiet after the last filesystem event before reindexing.
MARKDOWN_VAULT_MCP_FILE_WATCHER_ROOT_FLOORKeep the non-recursive watch on the vault root; set false to register zero source-dir-rooted FSEvents streams (avoids repeated macOS access prompts on a home-rooted vault) at the cost of root-level files relying on scans.
MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRETsecretShared secret for the GitHub push-event webhook; when set, mounts POST /github-webhook on HTTP/SSE transports to trigger an immediate pull + reindex on push events.
MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SIGNING_TOKENsecretSigning token for the GitLab push-event webhook (GitLab 19.0+); when set, mounts POST /gitlab-webhook on HTTP/SSE transports to trigger an immediate pull + reindex on push events. GitLab generates this value; copy the `whsec_` token it shows under Generate signing token rather than inventing one. Deliveries are authenticated by HMAC-SHA256 over the webhook id, timestamp and body, and a delivery older than 5 minutes is rejected.
MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SECRET_TOKENsecretSecret token for the GitLab push-event webhook, GitLab's plain-text form and the only one below 19.0; also mounts POST /gitlab-webhook. It proves nothing about the body and cannot expire, so prefer the signing token where the GitLab version offers it. Setting both accepts either, which is how an existing webhook migrates.
MARKDOWN_VAULT_MCP_SUMMARIZE_PROVIDERSummarization backend (only openai is recognised). Unset auto-detects: the backend activates when credentials or an explicit endpoint are present.
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEYsecretAPI key for the OpenAI-compatible summarize endpoint; the bare OPENAI_API_KEY is honoured as a fallback. Unset works for keyless local endpoints (Ollama).
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_BASE_URLOpenAI-compatible endpoint base URL for the summarize tool; setting it enables the tool even without an API key. The bare OPENAI_BASE_URL routes traffic only when a key already enables the feature.
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_MODELChat model id used for summaries.
MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_TOKENSUpper bound on generated tokens per summarize call; on reasoning models this budget also covers internal reasoning tokens.
MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_NOTESCap on the number of notes summarised in one call (subtree expansion truncates to this many).
MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_INPUT_CHARSAggregate cap on note characters sent to the model in one call; excess is truncated with a flag on the result.
MARKDOWN_VAULT_MCP_SUMMARIZE_TIMEOUTPer-request wall-clock budget in seconds for a single summarize backend call; keep it below the MCP client's request timeout so the server-side error wins the race.
MARKDOWN_VAULT_MCP_TRANSFER_TTL_DEFAULT_SLink lifetime in seconds when the caller requests no explicit TTL.
MARKDOWN_VAULT_MCP_TRANSFER_TTL_MAX_SCeiling in seconds a caller-requested link TTL is clamped to.
MARKDOWN_VAULT_MCP_TRANSFER_GRACE_TTL_SPost-success grace window in seconds: a served token's TTL shrinks to this so a stalled transfer can retry within it.
MARKDOWN_VAULT_MCP_TRANSFER_LEASE_SCrashed-handler reclaim window in seconds for an in-flight reservation.
MARKDOWN_VAULT_MCP_TRANSFER_MAX_UPLOAD_BYTESMaximum size in bytes of a single upload.
MARKDOWN_VAULT_MCP_JOBS_SOFT_DEADLINE_SSeconds a long-running tool call may run in the foreground before it is promoted to a background job and a job handle is returned instead.
MARKDOWN_VAULT_MCP_JOBS_RESULT_TTL_SSeconds a background-job record (working or finished) is retained for polling before it expires from the store.
MARKDOWN_VAULT_MCP_JOBS_MAX_PER_SUBJECTMaximum live background jobs per calling subject; further promotions are rejected until older records expire.

Own this server?

Claim it to keep the listing current and reply to reviews. Claiming never changes the grade or hides a review.

Claim listing

Badge for your README

Shows the safety grade and links back to this page. It updates itself after every scan and review.

[![mcp.market](https://mcp.market/badge/pvliesdonk-markdown-vault-mcp.svg)](https://mcp.market/server/pvliesdonk-markdown-vault-mcp)

How the badge works