# Markdown Vault MCP

> Markdown Vault MCP is a free MCP server for files and documents. Search, read and write a folder of Markdown notes with hybrid keyword and meaning search. It can run locally on your machine or as a hosted remote server.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** CLI, self-hosted, Linux
- **Website:** https://pvliesdonk.github.io/markdown-vault-mcp/
- **Repository:** https://github.com/pvliesdonk/markdown-vault-mcp
- **MCP Registry name:** io.github.pvliesdonk/markdown-vault-mcp
- **Categories:** files and documents, security, knowledge and memory
- **Listing updated:** 2026-11-14

## About

Point it at a folder of Markdown notes, and an Obsidian vault works as it is, and an assistant can search, read and edit them. Keyword search uses SQLite FTS5, and once an embedding provider is configured it adds search by meaning, fused by Reciprocal Rank Fusion with vectors held in SQLite, files or PostgreSQL. Results are short snippets, and read returns the whole section.

Writes are on by default and can be turned off with MARKDOWN_VAULT_MCP_READ_ONLY. Replacing a file needs the etag from reading it, per-folder _conventions.md rules reach the client as it writes, and an optional Git layer commits each write with history, diffs and read-back of an overwritten note. Link tools report backlinks, outlinks, broken links and the path between two notes, and YAML frontmatter fields become search filters.

The server runs over stdio or Streamable HTTP, and individual tools can be hidden through allow and deny lists. Embeddings can come from Ollama or OpenAI. A CLI can query a running vault remotely.

## Features

- **Hybrid search:** Combines FTS5 keyword search with optional embedding search.
- **Exact queries:** Pages, counts and aggregates indexed notes by frontmatter fields.
- **Guarded writes:** Needs an etag to replace a file and can be set read-only.
- **Git integration:** Commits writes optionally and reads back earlier revisions.
- **Link tools:** Finds backlinks, outlinks, broken links and note-to-note paths.
- **Tool allow and deny lists:** Hides selected tools from a given instance.

## Good for

- Let an assistant search a personal notes vault
- Edit and append to notes with conflict protection
- Find broken links in a knowledge base
- Count notes by tag
- Keep note edits under Git history

## Install

### Claude Code (Terminal)

```sh
claude mcp add markdown-vault-mcp --env OPENAI_API_KEY='<OPENAI_API_KEY>' --env VOYAGE_API_KEY='<VOYAGE_API_KEY>' --env MARKDOWN_VAULT_MCP_CLIENT_TOKEN='<MARKDOWN_VAULT_MCP_CLIENT_TOKEN>' --env MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN='<MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN>' --env MARKDOWN_VAULT_MCP_GIT_TOKEN='<MARKDOWN_VAULT_MCP_GIT_TOKEN>' --env MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET='<MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET>' --env MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SIGNING_TOKEN='<MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SIGNING_TOKEN>' --env MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SECRET_TOKEN='<MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SECRET_TOKEN>' --env MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY='<MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY>' -- uvx markdown-vault-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "markdown-vault-mcp": {
      "command": "uvx",
      "args": [
        "markdown-vault-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "VOYAGE_API_KEY": "<VOYAGE_API_KEY>",
        "MARKDOWN_VAULT_MCP_CLIENT_TOKEN": "<MARKDOWN_VAULT_MCP_CLIENT_TOKEN>",
        "MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN": "<MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN>",
        "MARKDOWN_VAULT_MCP_GIT_TOKEN": "<MARKDOWN_VAULT_MCP_GIT_TOKEN>",
        "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_OPENAI_API_KEY": "<MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "markdown-vault-mcp": {
      "command": "uvx",
      "args": [
        "markdown-vault-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "VOYAGE_API_KEY": "<VOYAGE_API_KEY>",
        "MARKDOWN_VAULT_MCP_CLIENT_TOKEN": "<MARKDOWN_VAULT_MCP_CLIENT_TOKEN>",
        "MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN": "<MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN>",
        "MARKDOWN_VAULT_MCP_GIT_TOKEN": "<MARKDOWN_VAULT_MCP_GIT_TOKEN>",
        "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_OPENAI_API_KEY": "<MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "markdown-vault-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "markdown-vault-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "VOYAGE_API_KEY": "<VOYAGE_API_KEY>",
        "MARKDOWN_VAULT_MCP_CLIENT_TOKEN": "<MARKDOWN_VAULT_MCP_CLIENT_TOKEN>",
        "MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN": "<MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN>",
        "MARKDOWN_VAULT_MCP_GIT_TOKEN": "<MARKDOWN_VAULT_MCP_GIT_TOKEN>",
        "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_OPENAI_API_KEY": "<MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "markdown-vault-mcp": {
      "command": "uvx",
      "args": [
        "markdown-vault-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "VOYAGE_API_KEY": "<VOYAGE_API_KEY>",
        "MARKDOWN_VAULT_MCP_CLIENT_TOKEN": "<MARKDOWN_VAULT_MCP_CLIENT_TOKEN>",
        "MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN": "<MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN>",
        "MARKDOWN_VAULT_MCP_GIT_TOKEN": "<MARKDOWN_VAULT_MCP_GIT_TOKEN>",
        "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_OPENAI_API_KEY": "<MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "markdown-vault-mcp": {
      "command": "uvx",
      "args": [
        "markdown-vault-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "VOYAGE_API_KEY": "<VOYAGE_API_KEY>",
        "MARKDOWN_VAULT_MCP_CLIENT_TOKEN": "<MARKDOWN_VAULT_MCP_CLIENT_TOKEN>",
        "MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN": "<MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN>",
        "MARKDOWN_VAULT_MCP_GIT_TOKEN": "<MARKDOWN_VAULT_MCP_GIT_TOKEN>",
        "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_OPENAI_API_KEY": "<MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY>"
      }
    }
  }
}
```

## Tools

- `read`: Fetch a whole note section
- `write`: Write a note
- `edit`: Edit a note
- `append`: Append to a note
- `delete`: Delete a note
- `rename`: Rename a note
- `move_folder`: Move a folder
- `fetch`: Fetch content into the vault
- `git_sync`: Sync with Git
- `create_upload_link`: Create an upload link
- `search_paths`: Find literal paths or nearby ASCII spellings
- `query_documents`: Page through indexed notes
- `count_documents`: Count every matching note
- `aggregate_documents`: Group the matching population into buckets

## FAQ

### Does it work with Obsidian?

Yes. The README says an Obsidian vault works as it is.

### Which embedding providers can it use?

Ollama and OpenAI are listed; search by meaning is off until one is configured.

### Can I make it read-only?

Yes, by setting MARKDOWN_VAULT_MCP_READ_ONLY=true.

### Where are vectors stored?

In SQLite, files or PostgreSQL.

### Is Markdown Vault MCP free?

Yes. Markdown Vault MCP is free to use.

### How do I add Markdown Vault MCP to Claude Code?

Run this command in your terminal: claude mcp add markdown-vault-mcp --env OPENAI_API_KEY='<OPENAI_API_KEY>' --env VOYAGE_API_KEY='<VOYAGE_API_KEY>' --env MARKDOWN_VAULT_MCP_CLIENT_TOKEN='<MARKDOWN_VAULT_MCP_CLIENT_TOKEN>' --env MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN='<MARKDOWN_VAULT_MCP_EMBEDDING_POSTGRES_DSN>' --env MARKDOWN_VAULT_MCP_GIT_TOKEN='<MARKDOWN_VAULT_MCP_GIT_TOKEN>' --env MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET='<MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET>' --env MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SIGNING_TOKEN='<MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SIGNING_TOKEN>' --env MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SECRET_TOKEN='<MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SECRET_TOKEN>' --env MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY='<MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY>' -- uvx markdown-vault-mcp

### What are the best alternatives to Markdown Vault MCP?

The closest alternatives to Markdown Vault MCP are REA, Codebase Memory, XERJ, Claude Code Ultimate Guide and Nautilus Compass Memory.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.
- [Agent Roast](https://ai-powered.com/mcp/agent-roast): Agent Roast is an open-source MCP server for developer tools.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [Leash](https://ai-powered.com/mcp/leash): Leash is a free MCP server for security.

---
Source: https://ai-powered.com/mcp/markdown-vault-mcp
