Markdown Vault MCP について
Markdown Vault MCP は、Markdown ノートのフォルダーを Claude などの MCP クライアントに提供し、検索・閲覧・編集できるサーバーです。キーワード検索と任意のセマンティック検索を組み合わせ、リンク分析や Git 同期にも対応します。
主な機能
- 01キーワードとセマンティック検索
- 02フロントマターによる絞り込み
- 03ノートの読み取りと編集
- 04ノート間リンクの分析
- 05任意の Git 同期
活用シーン
- 01ノート保管庫から情報を検索
- 02メタデータで長いノートを絞り込み
- 03ノート間のリンクを追跡
- 04Git で編集履歴を管理・同期
MCP 対応
MCP サーバーとして、保管庫の検索・読み取り・書き込み・リンク分析ツールを公開します。stdio または streamable HTTP で接続できます。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
mcp.json · 共通設定
起動コマンド
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 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。
ツール
ツール一覧はまだ取得されていません
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
Markdown Vault MCP
ハイブリッド検索に対応した汎用 Markdown vault MCP
ドキュメント | 設定ウィザード | PyPI | Docker
Claude やその他の MCP クライアントに、検索、読み取り、書き込みができる Markdown ノートのフォルダーを提供します。Obsidian vault はそのまま利用できます。
- ハイブリッド検索。 SQLite FTS5 によるキーワード検索に加え、埋め込みプロバイダーを設定すると、意味による検索も利用できます。検索結果は Reciprocal Rank Fusion で統合され、ベクトルはファイル、SQLite または PostgreSQL に保存されます。検索結果は短い抜粋で、
readを使うとセクション全体を取得できます。埋め込みを参照してください。 - データとしてのフロントマター。 YAML フロントマターのフィールドは検索フィルターになり、長いノートは見出しごとに分割されます。
- 慎重な書き込み。 書き込みツール（
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 統合を参照してください。
- リンク。 Wikilink と Markdown リンクのどちらでも、バックリンク、アウトリンク、リンク切れ、2 つのノート間のパスを確認できます。MCP Apps を表示できるクライアントでは、インタラクティブなビューも利用できます。
MARKDOWN_VAULT_MCP_REPORT_UNRESOLVED_LINKS=trueにすると、write、edit、appendは追加したリンクのうち解決できないものをそれぞれ示します。 - Open Knowledge Format。 OKF バンドルが認識され、検索結果には各ノートのタイプ、ステータス、信頼レベルが含まれます。OKFを参照してください。
ツールリファレンスには、すべてのツールが記載されています。同じエンジンは Python ライブラリとしても利用できます。Vault APIを参照してください。
適していますか？
サーバーがアクセスできる範囲、変更できる内容、アクセスできるユーザーについては、セキュリティモデルに記載されています。以下では、対象ユーザーと制限について説明します。
Markdown ファイルとしてノートを管理し、Claude に検索やリンクのたどり直し、ノートへの書き戻しをさせたい個人または小規模チームに適しています。自分のマシン上でも、共有サーバーとしても利用できます。アクセスできるのは vault フォルダーと、設定したもの（Git リモート、埋め込みモデルまたは要約モデル、fetch 呼び出しで指定した URL）のみです。
前提条件は次のとおりです。
- サーバーごとに vault は 1 つです。 現時点では、複数の vault にはそれぞれサーバーが必要です（#1232）。それぞれに
MARKDOWN_VAULT_MCP_SERVER_NAMEを設定してください。 - 検索対象は Markdown です。 PDF や画像などのその他のファイルは添付ファイルとして読み書きできますが、内容はまだインデックス化されません（#1234）。
- 埋め込みはメモリ上に保持されます。 意味による検索では、すべてのベクトルを 4 バイト × チャンク数 × 次元数のメモリに保持します。768 次元の 23,000 チャンクでは約 70 MB、チャンク数がその 10 倍で 1,024 次元の場合は約 900 MiB です。最初の制限となるのはクエリ時間ではなくメモリです（#1377）。
- 状態はローカルディスクに保存されます。 インデックスと埋め込みはファイルで、変更追跡ファイルはインデックスの隣に置かれ、vault の中には入りません。
MARKDOWN_VAULT_MCP_INDEX_PATHが設定されていない場合、インデックスと変更追跡ファイルはメモリ上に保持され、起動のたびに再構築されます。
数十万チャンクのコーパス（検索パイプラインの背後にベクトルデータベースを配置）、スキャン文書やオフィス文書が中心の環境（テキスト認識機能を備えた文書管理システム）、またはユーザー同士が互いのノートを閲覧できないようにする必要がある環境（マルチテナントのナレッジプラットフォーム）には、別のものをお使いください。サーバーがアクセスを許可した呼び出し元は、公開されているすべてのツールを利用できます。
クイックスタート
使用するクライアントを選んでください。各行ではリリース済みバージョンをインストールします。その後は、使い始めるチュートリアルに従ってください。
Claude Desktop。 リリースページから.mcpbバンドルをダウンロードし、Claude Desktopで開きます（または、設定 › 拡張機能 › 詳細設定 › 拡張機能をインストール…）。必要な設定はClaude Desktopが確認します。チュートリアル。
Claude Code。 Claude Code内で2つのコマンドを実行します。2つ目のコマンドではスコープを指定します。チュートリアル。
/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
リモートクライアント向けのサーバー（ストリーミング可能な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 Vault ディレクトリへのパスです。ディレクトリが存在しない場合、またはサーバーがアクセスできない場合でもサーバーは起動しますが、修正されるまで各ツールは原因を示すメッセージとともに失敗します（管理対象の Git モードでは、このディレクトリにクローンします）。Vault 内のシンボリックリンクは、Python 3.13 以降ではたどられます。 |
MARKDOWN_VAULT_MCP_READ_ONLY | false | いいえ | true に設定すると、書き込みツール（write、edit、append、delete、rename、move_folder、fetch、git_sync、okf_* ツール、create_upload_link）が非表示になり、検索専用の Vault として動作します。 |
MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTING | true | いいえ | if_match etag が指定されていない場合、既存ファイルを上書きする書き込みを拒否します。意図的な置き換えは引き続き可能です。先にファイルを読み取り、if_match を指定してください。edit、append、delete、rename には影響しません。無条件の上書きを許可するには false に設定します。 |
MARKDOWN_VAULT_MCP_REPORT_UNRESOLVED_LINKS | false | いいえ | true に設定すると、write、edit、append の呼び出しで追加されたリンクのうち、get_broken_links が報告するリンク先を unresolved_links に列挙します。ノートにすでに存在していたリンクは含まれません。デフォルトでは無効で、これらの応答は変更されません。 |
MARKDOWN_VAULT_MCP_DEFAULT_SEARCH_MODE | auto | いいえ | 検索呼び出しで 'mode' が省略された場合に使用するモードです。auto、keyword、semantic、hybrid を指定できます。デフォルトの 'auto' は、埋め込みが設定されている場合は hybrid、設定されていない場合は keyword を選択します。指定のない検索で埋め込みプロバイダーを使わないようにするには、'keyword' を指定します（hybrid または semantic 検索ではクエリを埋め込むため、従量制のプロバイダーでは API 呼び出し料金が発生します）。semantic または hybrid が設定されていても、埋め込みがなければ keyword に切り替わるため、どの設定でも Vault が検索不能になることはありません。明示的に指定された mode= 引数は切り替えられません。 |
MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER | (none) | いいえ | 埋め込みプロバイダーです。openai、voyage、ollama、fastembed を指定できます。設定すると、意味による検索が有効になります。未設定の場合は環境変数から自動検出します（voyage は対象外）。ただし、EMBEDDINGS_PATH が設定されているか、EMBEDDING_STORE=postgres の場合に限ります。openai と OPENAI_BASE_URL を使用すれば、OpenAI 互換のエンドポイントを利用できます。詳しくは埋め込みガイドをご覧ください。 |
MARKDOWN_VAULT_MCP_GIT_REPO_URL | (none) | いいえ | 管理対象の Git モードで使用する HTTPS リモート URL です。サーバーは起動時に空の SOURCE_DIR へクローンするか、既存の origin を検証し、プルのループ、自動コミット、遅延プッシュを有効にします。 |
MARKDOWN_VAULT_MCP_FILE_WATCHER | true | いいえ | 外部ファイルシステムによる変更を監視します。Git のプルが有効な場合、または Webhook で変更を受信できる場合（HTTP/SSE トランスポートのみ）は自動的に無効になります。file-watcher エクストラが必要です。 |
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_BASE_URL | (none) | いいえ | summarize ツール用の OpenAI 互換エンドポイントのベース URL です。設定すると、API キーがなくてもツールが有効になります。OPENAI_BASE_URL を単独で設定した場合、キーによってすでに機能が有効になっている場合にのみ、トラフィックがこの URL にルーティングされます。 |
サーバーが読み取るすべての変数（共通変数を含む）は、設定リファレンスに記載されています。.env.example には同じ設定項目がコピーして貼り付けられる形式で一覧表示されており、設定ウィザードを使うと、デプロイ用の設定ファイルを作成できます。
ドキュメント
- セキュリティモデル：サーバーがアクセスできる範囲、変更する内容、アクセスできるユーザーについて説明します。
- はじめに：クライアントで最初の操作を成功させる方法を紹介します。
- デプロイ：Docker、認証、OIDC、リバースプロキシについて説明します。
- 使い方：実際のタスクで使える機能を紹介します。
- リファレンス：設定、ツール、リソース、プロンプト、コマンドラインについて説明します。
- アップグレード：リリースチャネルと、アップグレードがクライアントやデータに与える変更について説明します。
- コントリビュート：ローカル開発、シークレット、修正の適切な配置場所について説明します。ルートには
CONTRIBUTING.mdとSECURITY.mdがあります。
設計上の決定
- ドキュメントの識別には相対パス（拡張子
.mdを含む）を使用します。デフォルトではフロントマターは任意です（REQUIRED_FIELDSを設定すると必須項目のチェックが有効になります）。 - ハイブリッド検索では Reciprocal Rank Fusion を使用します。FTS5 とベクトル検索の結果リストを統合し、ドキュメントごとのチャンク数に上限を設けた、多様性を考慮するランキングを行います。
- ツールの動作は Claude Code の Read／Write／Edit パターンに合わせています。そのため、LLM クライアントは使い慣れた操作方法でボルトを扱えます。
- ライブラリは同期式です。MCP レイヤーは呼び出しを
asyncio.to_thread()でラップします。ファイルへの書き込みは保存後に戻り、インデックスの更新はバックグラウンドで実行されます。インデックスに依存する変更は、先行する書き込みが完了するまで待機します。詳しくはインデックスの鮮度をご覧ください。 - インデックス作成にはハッシュを使用します。変更のないファイルは再解析されません。また、ノートのバイト列から保存済みの行を生成する方法に変更がある場合は、
INDEX_SEMANTICS_VERSIONを更新することで、デプロイ済みのボルトはアップグレード時に一度だけ自動で再構築されます。
設計上の決定事項の全記録は、設計ドキュメントにあります。
リンク
- ドキュメントとllms.txt
- このサーバーの基盤となっている FastMCP と fastmcp-pvl-core
- このリポジトリの生成に使用された fastmcp-server-template
コメント
Markdown 対応
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。