mcpField
M
Markdown Vault MCP

Markdown Vault MCP

本地服务
pvliesdonk.github.io记忆与知识35今天更新
代码仓库访问官网

关于 Markdown Vault MCP

Markdown Vault MCP 将 Markdown 笔记库提供给 Claude 等 MCP 客户端，适合个人或小团队搜索、读取和修改笔记。它结合关键词与可选语义搜索，并支持链接分析和 Git 同步。

主要功能

  1. 01关键词与语义混合搜索
  2. 02按 frontmatter 筛选
  3. 03读取和编辑笔记
  4. 04分析笔记链接
  5. 05可选 Git 同步

适用场景

  1. 01在笔记库中查找相关内容
  2. 02按属性筛选长篇笔记
  3. 03追踪笔记间的链接
  4. 04通过 Git 保存和同步修改

MCP 相关

作为 MCP 服务，它向客户端提供搜索、读取、写入及链接分析等工具。可通过 stdio 或 streamable HTTP 连接。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "pvliesdonk-markdown-vault": {
      "command": "uvx",
      "args": [
        "markdown-vault-mcp"
      ],
      "env": {
        "MARKDOWN_VAULT_MCP_KV_STORE_URL": "<MARKDOWN_VAULT_MCP_KV_STORE_URL>",
        "MARKDOWN_VAULT_MCP_TOOLS_ALLOW": "<MARKDOWN_VAULT_MCP_TOOLS_ALLOW>",
        "MARKDOWN_VAULT_MCP_TOOLS_DENY": "<MARKDOWN_VAULT_MCP_TOOLS_DENY>",
        "MARKDOWN_VAULT_MCP_SERVER_NAME": "<MARKDOWN_VAULT_MCP_SERVER_NAME>",
        "MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION": "<MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION>",
        "MARKDOWN_VAULT_MCP_INSTRUCTIONS_EXTRA": "<MARKDOWN_VAULT_MCP_INSTRUCTIONS_EXTRA>",
        "MARKDOWN_VAULT_MCP_INSTRUCTIONS": "<MARKDOWN_VAULT_MCP_INSTRUCTIONS>",
        "MARKDOWN_VAULT_MCP_LOG_LEVEL": "<MARKDOWN_VAULT_MCP_LOG_LEVEL>",
        "MARKDOWN_VAULT_MCP_LOG_FORMAT": "<MARKDOWN_VAULT_MCP_LOG_FORMAT>",
        "OLLAMA_HOST": "<OLLAMA_HOST>",
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "VOYAGE_API_KEY": "<VOYAGE_API_KEY>",
        "OPENAI_BASE_URL": "<OPENAI_BASE_URL>",
        "OPENAI_EMBEDDING_MODEL": "<OPENAI_EMBEDDING_MODEL>",
        "MARKDOWN_VAULT_MCP_BUILD_TIMEOUT_S": "<MARKDOWN_VAULT_MCP_BUILD_TIMEOUT_S>",
        "MARKDOWN_VAULT_MCP_DRAIN_TIMEOUT_S": "<MARKDOWN_VAULT_MCP_DRAIN_TIMEOUT_S>",
        "MARKDOWN_VAULT_MCP_SOURCE_DIR": "<MARKDOWN_VAULT_MCP_SOURCE_DIR>",
        "MARKDOWN_VAULT_MCP_READ_ONLY": "<MARKDOWN_VAULT_MCP_READ_ONLY>",
        "MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTING": "<MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTING>",
        "MARKDOWN_VAULT_MCP_REPORT_UNRESOLVED_LINKS": "<MARKDOWN_VAULT_MCP_REPORT_UNRESOLVED_LINKS>",
        "MARKDOWN_VAULT_MCP_DISABLE_APPS_UI": "<MARKDOWN_VAULT_MCP_DISABLE_APPS_UI>",
        "MARKDOWN_VAULT_MCP_INDEX_PATH": "<MARKDOWN_VAULT_MCP_INDEX_PATH>",
        "MARKDOWN_VAULT_MCP_STATE_PATH": "<MARKDOWN_VAULT_MCP_STATE_PATH>",
        "MARKDOWN_VAULT_MCP_EMBEDDINGS_PATH": "<MARKDOWN_VAULT_MCP_EMBEDDINGS_PATH>",
        "MARKDOWN_VAULT_MCP_INDEXED_FIELDS": "<MARKDOWN_VAULT_MCP_INDEXED_FIELDS>",
        "MARKDOWN_VAULT_MCP_REQUIRED_FIELDS": "<MARKDOWN_VAULT_MCP_REQUIRED_FIELDS>",
        "MARKDOWN_VAULT_MCP_EXCLUDE": "<MARKDOWN_VAULT_MCP_EXCLUDE>",
        "MARKDOWN_VAULT_MCP_TITLE_FIELD": "<MARKDOWN_VAULT_MCP_TITLE_FIELD>",
        "MARKDOWN_VAULT_MCP_SEARCHABLE_FIELDS": "<MARKDOWN_VAULT_MCP_SEARCHABLE_FIELDS>",
        "MARKDOWN_VAULT_MCP_TEMPLATES_FOLDER": "<MARKDOWN_VAULT_MCP_TEMPLATES_FOLDER>",
        "MARKDOWN_VAULT_MCP_PROMPTS_FOLDER": "<MARKDOWN_VAULT_MCP_PROMPTS_FOLDER>",
        "MARKDOWN_VAULT_MCP_CONVENTIONS_FILE": "<MARKDOWN_VAULT_MCP_CONVENTIONS_FILE>",
        "MARKDOWN_VAULT_MCP_OKF_MODE": "<MARKDOWN_VAULT_MCP_OKF_MODE>",
        "MARKDOWN_VAULT_MCP_OKF_WRITE": "<MARKDOWN_VAULT_MCP_OKF_WRITE>",
        "MARKDOWN_VAULT_MCP_OKF_VERIFY": "<MARKDOWN_VAULT_MCP_OKF_VERIFY>",
        "MARKDOWN_VAULT_MCP_ATTACHMENT_EXTENSIONS": "<MARKDOWN_VAULT_MCP_ATTACHMENT_EXTENSIONS>",
        "MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MB": "<MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MB>",
        "MARKDOWN_VAULT_MCP_MAX_NOTE_READ_BYTES": "<MARKDOWN_VAULT_MCP_MAX_NOTE_READ_BYTES>",
        "MARKDOWN_VAULT_MCP_DEFAULT_SEARCH_MODE": "<MARKDOWN_VAULT_MCP_DEFAULT_SEARCH_MODE>",
        "MARKDOWN_VAULT_MCP_CHUNKS_PER_FILE": "<MARKDOWN_VAULT_MCP_CHUNKS_PER_FILE>",
        "MARKDOWN_VAULT_MCP_SNIPPET_WORDS": "<MARKDOWN_VAULT_MCP_SNIPPET_WORDS>",
        "MARKDOWN_VAULT_MCP_LENGTH_DOWNWEIGHT_ALPHA": "<MARKDOWN_VAULT_MCP_LENGTH_DOWNWEIGHT_ALPHA>",
        "MARKDOWN_VAULT_MCP_MAX_CHUNK_WORDS": "<MARKDOWN_VAULT_MCP_MAX_CHUNK_WORDS>",
        "MARKDOWN_VAULT_MCP_MAX_CHUNK_CHARS": "<MARKDOWN_VAULT_MCP_MAX_CHUNK_CHARS>",
        "MARKDOWN_VAULT_MCP_CHUNK_OVERLAP_WORDS": "<MARKDOWN_VAULT_MCP_CHUNK_OVERLAP_WORDS>",
        "MARKDOWN_VAULT_MCP_FOLDER_WEIGHTS": "<MARKDOWN_VAULT_MCP_FOLDER_WEIGHTS>",
        "MARKDOWN_VAULT_MCP_FTS_WEIGHTS": "<MARKDOWN_VAULT_MCP_FTS_WEIGHTS>",
        "MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER": "<MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER>",
        "MARKDOWN_VAULT_MCP_OLLAMA_MODEL": "<MARKDOWN_VAULT_MCP_OLLAMA_MODEL>",
        "MARKDOWN_VAULT_MCP_OLLAMA_CPU_ONLY": "<MARKDOWN_VAULT_MCP_OLLAMA_CPU_ONLY>",
        "MARKDOWN_VAULT_MCP_VOYAGE_MODEL": "<MARKDOWN_VAULT_MCP_VOYAGE_MODEL>",
        "MARKDOWN_VAULT_MCP_OPENAI_BASE_URL": "<MARKDOWN_VAULT_MCP_OPENAI_BASE_URL>",
        "MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODEL": "<MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODEL>",
        "MARKDOWN_VAULT_MCP_FASTEMBED_MODEL": "<MARKDOWN_VAULT_MCP_FASTEMBED_MODEL>",
        "MARKDOWN_VAULT_MCP_FASTEMBED_CACHE_DIR": "<MARKDOWN_VAULT_MCP_FASTEMBED_CACHE_DIR>",
        "MARKDOWN_VAULT_MCP_EMBED_CONTEXT": "<MARKDOWN_VAULT_MCP_EMBED_CONTEXT>",
        "MARKDOWN_VAULT_MCP_EMBED_TIMEOUT_S": "<MARKDOWN_VAULT_MCP_EMBED_TIMEOUT_S>",
        "MARKDOWN_VAULT_MCP_EMBEDDING_BATCH_SIZE": "<MARKDOWN_VAULT_MCP_EMBEDDING_BATCH_SIZE>",
        "MARKDOWN_VAULT_MCP_GIT_TOKEN": "<MARKDOWN_VAULT_MCP_GIT_TOKEN>",
        "MARKDOWN_VAULT_MCP_GIT_REPO_URL": "<MARKDOWN_VAULT_MCP_GIT_REPO_URL>",
        "MARKDOWN_VAULT_MCP_GIT_USERNAME": "<MARKDOWN_VAULT_MCP_GIT_USERNAME>",
        "MARKDOWN_VAULT_MCP_GIT_PULL_INTERVAL_S": "<MARKDOWN_VAULT_MCP_GIT_PULL_INTERVAL_S>",
        "MARKDOWN_VAULT_MCP_GIT_PUSH_DELAY_S": "<MARKDOWN_VAULT_MCP_GIT_PUSH_DELAY_S>",
        "MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME": "<MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME>",
        "MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL": "<MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL>",
        "MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME_CLAIM": "<MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME_CLAIM>",
        "MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL_CLAIM": "<MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL_CLAIM>",
        "MARKDOWN_VAULT_MCP_GIT_LFS": "<MARKDOWN_VAULT_MCP_GIT_LFS>",
        "MARKDOWN_VAULT_MCP_FILE_WATCHER": "<MARKDOWN_VAULT_MCP_FILE_WATCHER>",
        "MARKDOWN_VAULT_MCP_FILE_WATCHER_DEBOUNCE_S": "<MARKDOWN_VAULT_MCP_FILE_WATCHER_DEBOUNCE_S>",
        "MARKDOWN_VAULT_MCP_FILE_WATCHER_ROOT_FLOOR": "<MARKDOWN_VAULT_MCP_FILE_WATCHER_ROOT_FLOOR>",
        "MARKDOWN_VAULT_MCP_BOOT_REINDEX": "<MARKDOWN_VAULT_MCP_BOOT_REINDEX>",
        "MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET": "<MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET>",
        "MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SIGNING_TOKEN": "<MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SIGNING_TOKEN>",
        "MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SECRET_TOKEN": "<MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SECRET_TOKEN>",
        "MARKDOWN_VAULT_MCP_SUMMARIZE_PROVIDER": "<MARKDOWN_VAULT_MCP_SUMMARIZE_PROVIDER>",
        "MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY": "<MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY>",
        "MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_BASE_URL": "<MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_BASE_URL>",
        "MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_MODEL": "<MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_MODEL>",
        "MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_TOKENS": "<MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_TOKENS>",
        "MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_NOTES": "<MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_NOTES>",
        "MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_INPUT_CHARS": "<MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_INPUT_CHARS>",
        "MARKDOWN_VAULT_MCP_SUMMARIZE_TIMEOUT": "<MARKDOWN_VAULT_MCP_SUMMARIZE_TIMEOUT>",
        "MARKDOWN_VAULT_MCP_TRANSFER_TTL_DEFAULT_S": "<MARKDOWN_VAULT_MCP_TRANSFER_TTL_DEFAULT_S>",
        "MARKDOWN_VAULT_MCP_TRANSFER_TTL_MAX_S": "<MARKDOWN_VAULT_MCP_TRANSFER_TTL_MAX_S>",
        "MARKDOWN_VAULT_MCP_TRANSFER_GRACE_TTL_S": "<MARKDOWN_VAULT_MCP_TRANSFER_GRACE_TTL_S>",
        "MARKDOWN_VAULT_MCP_TRANSFER_LEASE_S": "<MARKDOWN_VAULT_MCP_TRANSFER_LEASE_S>",
        "MARKDOWN_VAULT_MCP_TRANSFER_MAX_UPLOAD_BYTES": "<MARKDOWN_VAULT_MCP_TRANSFER_MAX_UPLOAD_BYTES>",
        "MARKDOWN_VAULT_MCP_JOBS_SOFT_DEADLINE_S": "<MARKDOWN_VAULT_MCP_JOBS_SOFT_DEADLINE_S>",
        "MARKDOWN_VAULT_MCP_JOBS_RESULT_TTL_S": "<MARKDOWN_VAULT_MCP_JOBS_RESULT_TTL_S>",
        "MARKDOWN_VAULT_MCP_JOBS_MAX_PER_SUBJECT": "<MARKDOWN_VAULT_MCP_JOBS_MAX_PER_SUBJECT>",
        "MARKDOWN_VAULT_MCP_SHUTDOWN_GRACE_S": "<MARKDOWN_VAULT_MCP_SHUTDOWN_GRACE_S>",
        "MARKDOWN_VAULT_MCP_BASE_URL": "<MARKDOWN_VAULT_MCP_BASE_URL>",
        "MARKDOWN_VAULT_MCP_BEARER_TOKEN": "<MARKDOWN_VAULT_MCP_BEARER_TOKEN>",
        "MARKDOWN_VAULT_MCP_OIDC_CONFIG_URL": "<MARKDOWN_VAULT_MCP_OIDC_CONFIG_URL>",
        "MARKDOWN_VAULT_MCP_OIDC_CLIENT_ID": "<MARKDOWN_VAULT_MCP_OIDC_CLIENT_ID>",
        "MARKDOWN_VAULT_MCP_OIDC_CLIENT_SECRET": "<MARKDOWN_VAULT_MCP_OIDC_CLIENT_SECRET>",
        "MARKDOWN_VAULT_MCP_OIDC_AUDIENCE": "<MARKDOWN_VAULT_MCP_OIDC_AUDIENCE>",
        "MARKDOWN_VAULT_MCP_OIDC_REQUIRED_SCOPES": "<MARKDOWN_VAULT_MCP_OIDC_REQUIRED_SCOPES>",
        "MARKDOWN_VAULT_MCP_OIDC_ADVERTISED_SCOPES": "<MARKDOWN_VAULT_MCP_OIDC_ADVERTISED_SCOPES>",
        "MARKDOWN_VAULT_MCP_OIDC_JWT_SIGNING_KEY": "<MARKDOWN_VAULT_MCP_OIDC_JWT_SIGNING_KEY>",
        "MARKDOWN_VAULT_MCP_OIDC_VERIFY_ACCESS_TOKEN": "<MARKDOWN_VAULT_MCP_OIDC_VERIFY_ACCESS_TOKEN>",
        "MARKDOWN_VAULT_MCP_APP_DOMAIN": "<MARKDOWN_VAULT_MCP_APP_DOMAIN>",
        "MARKDOWN_VAULT_MCP_AUTH_MODE": "<MARKDOWN_VAULT_MCP_AUTH_MODE>",
        "MARKDOWN_VAULT_MCP_BEARER_TOKENS_FILE": "<MARKDOWN_VAULT_MCP_BEARER_TOKENS_FILE>",
        "MARKDOWN_VAULT_MCP_BEARER_DEFAULT_SUBJECT": "<MARKDOWN_VAULT_MCP_BEARER_DEFAULT_SUBJECT>",
        "MARKDOWN_VAULT_MCP_HTTP_PATH": "<MARKDOWN_VAULT_MCP_HTTP_PATH>",
        "MARKDOWN_VAULT_MCP_HEALTH_DETAIL": "<MARKDOWN_VAULT_MCP_HEALTH_DETAIL>",
        "PUID": "<PUID>",
        "PGID": "<PGID>"
      }
    }
  }
}
启动命令uvx markdown-vault-mcp
需要配置的环境变量
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).
MARKDOWN_VAULT_MCP_LOG_LEVELLog level for every logger in the process, FastMCP's included (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG. The unprefixed FASTMCP_LOG_LEVEL still works for one major version and logs a deprecation warning.
MARKDOWN_VAULT_MCP_LOG_FORMATLog rendering. rich is one colour event key=value line per record, for a terminal; json is one JSON object per record, for a collector. Unset picks rich when stderr is a terminal and json everywhere else, so a container or journald gets JSON with no configuration.
OLLAMA_HOSTOllama server URL for the ollama embedding provider. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the Ollama ecosystem convention.
OPENAI_API_KEY密钥OpenAI 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_KEY密钥Voyage 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. When it does not exist, or the server cannot access it, the server starts but every tool fails with a message saying which until it is fixed (managed git mode clones into 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.
MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTINGRefuse 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. Set to false to allow blind overwrites.
MARKDOWN_VAULT_MCP_REPORT_UNRESOLVED_LINKSSet to true to have write, edit and append list, under unresolved_links, the target of each link the call added that get_broken_links reports. Links the note already held are left out. Off by default, leaving those responses unchanged.
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 INDEX_PATH plus .state.json (index.db.state.json beside index.db); without INDEX_PATH the state is kept in memory. Never written into the vault by default.
MARKDOWN_VAULT_MCP_EMBEDDINGS_PATHBase path for the embeddings files. Defaults beside INDEX_PATH (index-db-embeddings.npy and .json beside index.db); without INDEX_PATH the vectors are kept in memory and rebuilt at each start. Setting it also lets the provider be auto-detected.
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 a token's sub claim with no confirmation; it rejects static bearer credentials and other client-ID-only identities. This 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; setting it turns on search by meaning. Unset auto-detects from the environment (never voyage), but only when EMBEDDINGS_PATH is set. 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_TOKEN密钥Token/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, and the author name too unless an OIDC claim supplies one; set this in Docker where git config user.name is empty.
MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAILGit committer email for auto-commits, and the author email too unless an OIDC claim supplies one.
MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME_CLAIMOIDC claim key used as the commit author name (e.g. name) when an OIDC token is present; the committer stays GIT_COMMIT_NAME. 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) when an OIDC token is present; the committer stays GIT_COMMIT_EMAIL. 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_BOOT_REINDEXReconcile offline changes at startup by reindexing once the initial build completes. Set false on a large vault to start without paying a full filesystem scan per server start; changes made while no server was running are then invisible until a reindex runs (the reindex tool, or 'markdown-vault-mcp reindex'). Note that `index_stale` reports writer idleness, not agreement with disk, so it reads false while the index may still differ from the vault.
MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET密钥Shared 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_TOKEN密钥Signing 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_TOKEN密钥Secret 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_KEY密钥API 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_TOKENS密钥Upper 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_SHUTDOWN_GRACE_SSeconds SIGTERM may spend draining in-flight requests before the HTTP server exits. Keep it at or below the termination grace period the orchestrator allows. `0` drops in-flight requests immediately.
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_TOKEN密钥Single 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_SECRET密钥OIDC 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_KEY密钥Signing 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_TOKEN密钥Validate the access token instead of the id token.
MARKDOWN_VAULT_MCP_APP_DOMAINMCP Apps iframe domain, used for CSP sandboxing. Overrides the host derived from `base_url`.
MARKDOWN_VAULT_MCP_AUTH_MODE密钥Explicit 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_FILE密钥Path 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_HTTP_PATHMount path for the MCP endpoint; the health routes derive their prefix from it.
MARKDOWN_VAULT_MCP_HEALTH_DETAILHow much the unauthenticated /health and /health/ready bodies say: status, standard (adds name, version and per-check verdicts), or full (adds redacted reasons; trusted networks only).
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.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypimarkdown-vault-mcp5.1.0
ocighcr.io/pvliesdonk/markdown-vault-mcp:v5.1.0

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Markdown Vault MCP 徽标

Markdown Vault MCP

CI Quality Gate Status Coverage Reliability Rating Security Rating PyPI Python 许可证 Docker 文档 llms.txt 模板

通用 Markdown 知识库 MCP，支持混合搜索

文档 | 配置向导 | PyPI | Docker

为 Claude 或任何 MCP 客户端提供一个 Markdown 笔记文件夹，以便搜索、阅读和写入。Obsidian 知识库可以直接使用。

  • 混合搜索。 使用 SQLite FTS5 进行关键词搜索；配置嵌入提供商后，还可按含义搜索，并通过 Reciprocal Rank Fusion 融合结果。向量可存储在文件、SQLite 或 PostgreSQL 中。搜索结果是简短片段；read 会获取完整章节。请参阅嵌入。
  • 将 Frontmatter 作为数据。 YAML Frontmatter 字段会成为搜索筛选条件，较长的笔记会按标题拆分。
  • 谨慎写入。 写入工具（write、edit、append、delete、rename、move_folder、fetch、git_sync、okf_* 工具、create_upload_link）默认启用；当 MARKDOWN_VAULT_MCP_READ_ONLY=true 时会隐藏。替换文件时会使用读取文件时获取的 etag；写入过程中，每个文件夹中的 _conventions.md 规则也会传递给客户端。
  • Git。 可选的每次写入提交，并支持延迟推送、拉取或 webhook 同步，以及历史记录和差异；被覆盖的笔记可以按其被替换时的修订版本读取。请参阅 Git 集成。
  • 链接。 支持维基链接和 Markdown 链接的反向链接、出链、损坏链接，以及两篇笔记之间的路径；可在能呈现 MCP Apps 的客户端中交互式查看。启用 MARKDOWN_VAULT_MCP_REPORT_UNRESOLVED_LINKS=true 后，write、edit 和 append 会列出它们新增的每个未解析链接。
  • 开放知识格式。 系统可识别 OKF 包，搜索结果会附带每篇笔记的类型、状态和信任层级。请参阅 OKF。

工具参考列出了所有工具。同一引擎也提供 Python 库：请参阅 Vault API。

适合你吗？

服务器可以访问什么、会更改什么，以及谁能使用服务器，都在安全模型中说明；下文则介绍它适用的用户和限制。

它适合使用 Markdown 文件保存笔记、希望 Claude 能搜索笔记、跟随笔记中的链接并写回内容的个人或小型团队，可在自己的机器上使用，也可作为共享服务使用。它只能访问 Vault 文件夹，以及你配置的内容：Git 远程端、嵌入或摘要模型，以及 fetch 调用指定的网址。

它的适用前提：

  • 每个服务对应一个 Vault。 目前，多个 Vault 需要分别使用一个服务（#1232）；请为每个服务设置 MARKDOWN_VAULT_MCP_SERVER_NAME。
  • 只搜索 Markdown。 其他文件（例如 PDF 和图片）可以作为附件读取和写入，但其内容尚未编入索引（#1234）。
  • 嵌入保存在内存中。 按含义搜索时，所有向量都会占用 4 字节 × 分块数 × 维度数的内存：23,000 个分块、768 维时约为 70 MB；规模扩大 10 倍且维度为 1,024 时约为 900 MiB。首先遇到的限制是内存，而非查询时间（#1377）。
  • 状态存储在本地磁盘。 索引和嵌入均为文件；变更跟踪文件位于索引旁边，绝不会放在 Vault 中。未设置 MARKDOWN_VAULT_MCP_INDEX_PATH 时，索引和该文件会保存在内存中，并在每次启动时重新构建。

如果你要处理数十万个分块的语料（应在检索管道后端使用向量数据库）、主要是扫描件或办公文档（应使用带文字识别功能的文档管理系统），或有许多用户且必须彼此隔离笔记（应使用多租户知识平台），建议选择其他方案：服务器允许的每个调用方都能使用服务器公开的所有工具。

快速开始

选择你使用的客户端。每一行都会安装已发布的版本；开始使用教程会接着介绍后续步骤。

Claude Desktop。 从发布页面下载 .mcpb 捆绑包，并用 Claude Desktop 打开（或选择 Settings › Extensions › Advanced settings › Install Extension…）。Claude Desktop 会自行询问所需设置。教程。

Claude Code。 在 Claude Code 中运行两条命令；第二条会询问作用范围。教程。

/plugin marketplace add pvliesdonk/claude-plugins
/plugin install markdown-vault-mcp@pvliesdonk

运行命令的客户端（stdio）。要在 Claude Code 中注册，请参阅 Claude Code 教程。

uv tool install "markdown-vault-mcp"
markdown-vault-mcp serve

供远程客户端使用的服务（streamable HTTP）。远程服务负责连接各客户端。

docker run --rm -p 8000:8000 --env-file .env ghcr.io/pvliesdonk/markdown-vault-mcp:latest

仓库根目录提供了 compose.yml，可直接运行：将 .env.example 复制为 .env，然后运行 docker compose up -d。部署介绍了身份验证、OIDC、反向代理和系统软件包（发布页面提供 .deb/.rpm）。服务会在 MCP 挂载点之外响应 /health 和 /health/ready，其 get_server_info 工具会报告正在运行的版本。

基础软件包包含关键词搜索、写入工具和 git。按含义搜索、文件监视器、summarize 工具以及在 PostgreSQL 中保留嵌入向量需要额外组件；[all] 会安装所有组件：

uv tool install "markdown-vault-mcp[all]"

Docker 镜像、.mcpb 捆绑包和 Claude Code 插件已包含这些组件。安装列出了各项额外组件。

配置

所有配置都通过带有 MARKDOWN_VAULT_MCP_ 前缀的环境变量完成。大多数安装会设置以下变量：

变量默认值必需说明
MARKDOWN_VAULT_MCP_SOURCE_DIR/data/vault否Markdown 知识库目录的路径。如果该目录不存在，或服务无法访问它，服务仍会启动，但所有工具都会失败，并提示具体问题，直到问题得到解决（托管 Git 模式会克隆到该目录中）。Python 3.13+ 会跟随知识库中的符号链接。
MARKDOWN_VAULT_MCP_READ_ONLYfalse否设为 true 可隐藏写入工具（write、edit、append、delete、rename、move_folder、fetch、git_sync、okf_* 工具、create_upload_link），并提供仅支持搜索的知识库。
MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTINGtrue否未提供 if_match etag 时，拒绝会覆盖现有文件的写入。仍可主动替换文件：先读取文件，再传入 if_match。此设置不影响：edit、append、delete、rename。设为 false 可允许无条件覆盖。
MARKDOWN_VAULT_MCP_REPORT_UNRESOLVED_LINKSfalse否设为 true 后，write、edit 和 append 会在 unresolved_links 下列出本次调用添加的、由 get_broken_links 报告的各个链接目标。笔记中原有的链接不会列出。默认关闭，因此这些响应保持不变。
MARKDOWN_VAULT_MCP_DEFAULT_SEARCH_MODEauto否搜索调用未指定 'mode' 时使用的模式：auto、keyword、semantic 或 hybrid。默认的 'auto' 会在配置了嵌入时选择 hybrid，未配置时选择 keyword。设为 'keyword' 可让未指定模式的搜索不调用嵌入服务提供方（每次 hybrid 或 semantic 搜索都会对查询进行嵌入；如果服务提供方按用量计费，这会产生 API 调用费用）。如果未配置嵌入，已配置的 semantic/hybrid 默认值也会降级为 keyword，因此不会有任何设置导致知识库无法搜索；显式指定的 mode= 参数不会降级。
MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER（无）否嵌入服务提供方：openai、voyage、ollama 或 fastembed；设置此项即可启用语义搜索。未设置时会从环境中自动检测（不会检测 voyage），但仅当设置了 EMBEDDINGS_PATH 或 EMBEDDING_STORE=postgres 时才会检测。任何兼容 OpenAI 的端点都可通过 openai 和 OPENAI_BASE_URL 使用；详见嵌入指南。
MARKDOWN_VAULT_MCP_GIT_REPO_URL（无）否托管 Git 模式的 HTTPS 远程 URL：服务启动时会克隆到空的 SOURCE_DIR（或验证已有的 origin），并启用拉取循环、自动提交和延迟推送。
MARKDOWN_VAULT_MCP_FILE_WATCHERtrue否监视知识库中的外部文件系统更改；当 Git 拉取处于活动状态或可通过 webhook 接收更改时（仅限 HTTP/SSE 传输），会自动禁用。需要安装 file-watcher 附加组件。
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_BASE_URL（无）否summarize 工具的 OpenAI 兼容端点基础 URL；设置此项后，即使没有 API 密钥也会启用该工具。只有在 API 密钥已启用此功能时，未加前缀的 OPENAI_BASE_URL 才会路由流量。

服务读取的所有变量（包括共享变量）都列在配置参考中；.env.example 以便于复制粘贴的形式列出了相同的配置项，配置向导则会为你的部署生成配置文件。

文档

  • 安全模型：服务可以访问哪些内容、会修改哪些内容，以及谁可以访问。
  • 开始使用：让客户端首次成功运行。
  • 部署：Docker、身份验证、OIDC、反向代理。
  • 使用：了解各项功能，并将其用于实际任务。
  • 参考：配置、工具、资源、提示词、命令行。
  • 升级：发布渠道，以及升级对客户端和数据的影响。
  • 贡献：本地开发、密钥，以及修复应归属的位置；根目录中的 CONTRIBUTING.md 和 SECURITY.md。

设计决策

  • 文档的标识是带有 .md 扩展名的相对路径；默认情况下，frontmatter 是可选的（REQUIRED_FIELDS 可启用强制校验）。
  • 混合搜索使用倒数排名融合，融合 FTS5 和向量结果列表，并通过限制每篇文档的分块数量来实现多样性排序。
  • 工具语义与 Claude Code 的 Read/Write/Edit 模式一致，让大模型客户端能用熟悉的习惯操作知识库。
  • 该库采用同步方式；MCP 层通过 asyncio.to_thread() 封装调用。文件写入会在保存后返回，而索引更新则在后台运行。依赖索引的修改会等待之前的写入完成；详见索引在写入后的新鲜度。
  • 索引基于哈希：未更改的文件绝不会重新解析；如果存储行的生成方式因笔记字节内容而变化，就会递增 INDEX_SEMANTICS_VERSION，使已部署的知识库在升级时自行重建一次。

完整的决策日志见设计文档。

链接

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。