OB
SearchProductivity

Obsidian MCP Server for Note Management

Manage and organize Obsidian notes with an MCP server offering search, read, write, and note organization tools by Steven Stavrakis.

View on GitHub
Quick Install
npx -y @StevenStavrakis/obsidian-mcp

Overview

The Obsidian MCP Server for Note Management is a lightweight server that exposes a Model Context Protocol (MCP) interface around an Obsidian vault. It lets LLMs and other automated agents query, read, write, and reorganize notes programmatically. By translating common note operations into a standardized MCP toolset, the server makes it easier to integrate Obsidian content into automated workflows such as summarization, semantic search, and note refactoring.

This server is useful when you want external tools (or LLMs) to access an Obsidian vault without opening the GUI. Typical scenarios include enhancing search with embeddings, letting agents create or rewrite notes, generating outlines based on existing content, and keeping metadata consistent across files. The server is designed for developers who want to add programmatic note management to applications or AI agents while maintaining local vault structure and frontmatter.

Features

  • Expose Obsidian vault content via an MCP-compatible API
  • Full-text and metadata search across notes
  • Read and stream note content, including frontmatter and links
  • Create, update, and delete notes programmatically
  • Move and rename files to support reorganization
  • Tools for extracting and updating note metadata (frontmatter)
  • Simple auth and configurable vault path
  • Optional Docker image and node/npm-based setup

Installation / Configuration

Prerequisites:

  • Node.js 18+ (or use Docker)
  • Local Obsidian vault path accessible to the server

Clone and install:

git clone https://github.com/StevenStavrakis/obsidian-mcp.git
cd obsidian-mcp
npm install

Create a configuration file (config.json) in the project root or set environment variables:

{
  "VAULT_PATH": "/home/user/ObsidianVault",
  "PORT": 3000,
  "API_KEY": "change-me",
  "ENABLE_WRITE": true
}

Start the server:

# using environment variables
VAULT_PATH="/home/user/ObsidianVault" PORT=3000 API_KEY="secret" npm start

# or with config.json (if supported by the project)
node ./dist/index.js --config ./config.json

Docker (example):

docker build -t obsidian-mcp .
docker run -e VAULT_PATH="/vault" -e API_KEY="secret" -v /local/vault:/vault -p 3000:3000 obsidian-mcp

Configuration options (summary):

OptionTypeDefaultDescription
VAULT_PATHstring—Filesystem path to your Obsidian vault
PORTnumber3000HTTP port the server listens on
API_KEYstring—Simple API key for requests
ENABLE_WRITEbooleanfalseWhether write/mutation endpoints are allowed

Available Tools / Resources

The server exposes a set of MCP tools (HTTP endpoints) that map to common note operations. Example endpoints and JSON schemas:

  • GET /health

    • Simple status check.

  • POST /mcp/search

    • Body: { “query”: “meeting notes project X”, “limit”: 10 }
    • Returns a ranked list of matching notes with snippets and metadata.

  • GET /mcp/read?path=Notes/meeting.md

    • Returns full note content and frontmatter.

  • POST /mcp/write

    • Body: { “path”: “Notes/new-note.md”, “content”: “# Title\nContent”, “createIfMissing”: true }
    • Writes content to file; returns status and new file metadata.

  • POST /mcp/rename

    • Body: { “oldPath”: “Notes/old.md”, “newPath”: “Notes/new.md” }
    • Rename/move a file in the vault.

  • POST /mcp/metadata

    • Body: { “path”: “Notes/todo.md”, “frontmatter”: { “tags”: [“todo”], “status”: “open” } }
    • Read or update frontmatter metadata.

Example search request:

curl -X POST "http://localhost:3000/mcp/search" \
  -H "Authorization: Bearer secret" \
  -H "Content-Type: application/json" \
  -d '{"query":"weekly summary","limit":5}'

Example read request:

curl "http://localhost:3000/mcp/read?path=Notes%2Fweekly-summary.md" \
  -H "Authorization: Bearer secret"

Responses are JSON and designed to be easily consumed by an LLM or automation pipeline.

Use Cases

  • Semantic search integration

    • Use the /mcp/search endpoint to power an LLM-based assistant that retrieves relevant notes before answering user questions.

  • Automated note creation and templates

    • Generate a meeting note from an LLM, then call /mcp/write to store it in the vault with appropriate frontmatter (date, attendees, tags).

  • Batch metadata cleanup

    • Read frontmatter across many files and use /mcp/metadata to apply consistent tags, statuses, or link corrections.

  • Reorganization workflows

    • Run a refactoring agent that renames and moves notes to enforce a folder structure. Use /mcp/rename to update files and /mcp/read to adjust affected backlinks or embeds.

  • Summarization and flashcard generation

    • Retrieve source notes with /mcp/read, run summarization or Q/A generation externally, and write summaries or flashcards back into the vault.

Tips for Developers

  • Run with ENABLE_WRITE=false during testing to prevent accidental modifications.
  • Keep a backup of your vault before running automated reorganization tools.
  • Use API_KEY (or integrate with a reverse proxy) to restrict access to the local MCP server.
  • Combine the MCP tools with embeddings/search libraries to build richer retrieval-augmented generation (RAG) pipelines.

For implementation details, API contract, and advanced configuration, refer to the project’s GitHub repository to inspect source code and examples.

Tags:productivitysearch