Obsidian Notes MCP Server Secure File Vault Access

Overview

This MCP (Model Context Protocol) server exposes an Obsidian vault as a secure, file-aware context provider for LLMs, editors, and automation tools. Instead of running the Obsidian desktop app, clients can query, search, and stream individual Markdown files through a small HTTP API that enforces file-level access controls and supports rich discovery features like Maps of Content (MOC) extraction.

The server is useful for developers integrating Obsidian content into AI workflows, editor plugins (for example obsidian.nvim), or agent systems that need reliable, provable retrieval. It focuses on privacy and safety: only files permitted via configuration are served, authentication tokens are supported, and the API is designed to keep file boundaries explicit so downstream models can reference exact sources.

Features

• Secure file-level access: restrict which files or folders can be served
• Token-based authentication (Bearer tokens) and optional TLS
• Advanced search: full-text, path-aware, and fuzzy matching
• MOC (Map of Content) discovery: detect and traverse MOC files and backlinks
• Obsidian-compatible semantics: respects Markdown links and attachments
• obsidian.nvim friendly: designed for editor integrations that need remote vault access
• Lightweight HTTP API that conforms to common MCP patterns (context, tools, resources)

Installation / Configuration

Quick start (Docker recommended):

1. Clone repository:

git clone https://github.com/Piotr1215/mcp-obsidian.git
cd mcp-obsidian

2. Build and run with Docker (example):

# Build image (if no prebuilt image)
docker build -t mcp-obsidian .

# Run container, mount your vault, expose port 8080
docker run -d \
  -v /path/to/your/vault:/vault:ro \
  -e MCP_OBSIDIAN_VAULT="/vault" \
  -e MCP_AUTH_TOKEN="your-secret-token" \
  -p 8080:8080 \
  mcp-obsidian

Alternative: run locally (if repository includes a Node or Rust binary). Example commands assume a built binary named mcp-obsidian:

# Example environment variables
export MCP_OBSIDIAN_VAULT="/home/user/notes"
export MCP_AUTH_TOKEN="your-secret-token"
export MCP_PORT=8080

./mcp-obsidian --config ./config.yml

Sample configuration (YAML):

vault_path: /vault
port: 8080
auth_token: your-secret-token
allow_paths:
  - "Daily/"
  - "Projects/"
search:
  fuzzy: true
  max_results: 50
moc_discovery: true
obsidian_nvim_compat: true

Configuration options (summary):

Security notes:

• Run behind TLS or a reverse proxy if exposing over public networks.
• Use restrictive allow_paths for multi-tenant or shared environments.
• Rotate auth tokens and limit privileges.

Available Resources

The server exposes REST-style endpoints suitable for MCP-style retrieval. Example endpoints:

• GET /health
• GET /files?path= — list files under a vault path
• GET /file?path= — fetch raw Markdown of a single file
• POST /search — body: { “q”: “query”, “limit”: 10 }
• GET /moc?path= — return MOC links or the MOC graph for a file

  Example curl requests:

  # List files
  curl -H "Authorization: Bearer your-secret-token" "http://localhost:8080/files?path=Projects"
  
  # Read a file
  curl -H "Authorization: Bearer your-secret-token" "http://localhost:8080/file?path=Projects/Plan.md"
  
  # Search
  curl -H "Authorization: Bearer your-secret-token" \
    -H "Content-Type: application/json" \
    -d '{"q":"deployment checklist","limit":5}' \
    http://localhost:8080/search
  

  Responses are JSON and include provenance for each returned result (file path, line ranges, snippet) so LLMs can cite exact sources.

  Use Cases

  • LLM-assisted note authoring: A chatbot uses the server to fetch relevant notes and MOCs to provide context-aware suggestions or to generate summaries citing exact files and sections.
  • obsidian.nvim remote vault: A Neovim plugin configured to use this MCP server can open and edit vault files remotely without running the Obsidian desktop app locally.
  • Automated knowledge ingestion: Agents or CI jobs can index, search, and transform vault content for reporting, migration, or backup processes while respecting file-level access rules.
  • Secure knowledge base for teams: Host the vault on a trusted server and expose only allowed folders to automated systems (e.g., an internal assistant) via tokenized access, reducing risk of over-sharing.

  Getting Help / Contributing

  Repository and source code: https://github.com/Piotr1215/mcp-obsidian

  When filing issues or PRs, include:

  • Vault layout (sensitive paths redacted)
  • Configuration file used
  • Example request and server log snippets demonstrating the behavior you expect vs. observed

  This server is intended for developers integrating Obsidian content into AI and editor tooling; contributions that improve security, search quality, and obsidian.nvim compatibility are especially welcome.

  Tags:files-storageproductivitysearch