Skip to main content
Glama
darrenlopez

obsidian-mcp

by darrenlopez
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

obsidian-mcp

A Model Context Protocol server that lets any MCP-compatible AI host (Cursor, Claude Desktop, Zed, etc.) read, search, link, and write notes inside a local Markdown / Obsidian vault.

CI Python 3.11+ License: MIT

What is this?

obsidian-mcp is an MCP server. MCP is an open standard from Anthropic for connecting AI assistants to external tools and data sources — think "USB-C for AI applications". Once this server is registered with an MCP host you can ask the model questions like:

"What did I learn about MCP this week, and which of my notes link to it?"

…and the model will call this server's tools (search_notes, find_backlinks, get_recent_notes, …) to answer using your actual notes.

Related MCP server: Obsidian MCP Server

Status

Phase

Scope

State

0

Repo skeleton, CI, sample vault, server stub with get_note

shipped

1

Sandboxed pathing, parser, reader, tests

shipped

2

Search, listings, backlinks, tag index

planned

3

Resources (notes as obsidian:// URIs)

planned

4

Write tools (create_note, append_to_note) + atomic writes

planned

5

Prompts (/weekly-review, /daily-note-template)

planned

Architecture

┌────────────────┐    stdio JSON-RPC    ┌────────────────────────┐
│  MCP host      │ ───────────────────► │  obsidian-mcp server   │
│ (Cursor /      │                      │  (this repo)           │
│  Claude /      │                      │                        │
│  Zed)          │                      │  tools / resources /   │
└────────────────┘                      │  prompts               │
                                        └───────────┬────────────┘
                                                    │
                                        sandboxed   ▼
                                        ┌────────────────────────┐
                                        │  Local Markdown vault  │
                                        └────────────────────────┘

Every caller-supplied path is funnelled through a single sandboxing function (utils/pathing.py::safe_resolve) before any filesystem access, so the server cannot be coerced into reading files outside the configured vault root.

Quickstart

1. Install

git clone https://github.com/darrenlopez/obsidian-mcp.git
cd obsidian-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

2. Try it against the bundled sample vault

OBSIDIAN_MCP_VAULT_PATH="$(pwd)/sample-vault" \
  npx @modelcontextprotocol/inspector \
  python -m obsidian_mcp

This launches Anthropic's official MCP Inspector pointed at this server, so you can interactively call get_note and inspect schemas without leaving your browser.

3. Register with Cursor

Add the following to your Cursor MCP config (~/.cursor/mcp.json or the Cursor settings UI):

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["-m", "obsidian_mcp"],
      "env": {
        "OBSIDIAN_MCP_VAULT_PATH": "/absolute/path/to/your/vault",
        "OBSIDIAN_MCP_READ_ONLY": "false"
      }
    }
  }
}

4. Register with Claude Desktop

Add the same block to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or the platform equivalent).

Configuration

All configuration is via environment variables (prefix OBSIDIAN_MCP_).

Variable

Default

Purpose

OBSIDIAN_MCP_VAULT_PATH

(required)

Absolute path to the vault root.

OBSIDIAN_MCP_READ_ONLY

false

When true, write tools are not registered.

OBSIDIAN_MCP_MAX_FILE_KB

1024

Max note size (KiB) returned by read operations.

OBSIDIAN_MCP_INCLUDE_HIDDEN

false

Include dotfiles and .obsidian/ in listings/search.

Tools (Phase 0 / 1)

Tool

Description

get_note(path)

Read a single note, returning parsed frontmatter, tags, and outgoing wikilinks.

The Phase 2+ tool surface (search_notes, list_notes, find_backlinks, list_tags, get_recent_notes, …) is documented in the architecture plan and tracked in STATUS.

Security

This server reads (and, in non-read-only mode, writes) files on your machine. Some choices that limit blast radius:

  • Sandboxed paths. Every path is resolved through safe_resolve(vault_root, user_input), which rejects absolute paths, .. segments, and symlink escapes before any filesystem touch.

  • Read-only mode. Set OBSIDIAN_MCP_READ_ONLY=true and write tools are not registered at all.

  • Size limits. OBSIDIAN_MCP_MAX_FILE_KB caps the bytes returned by read operations to prevent DoS via huge files.

  • Hidden-file exclusion. .obsidian/ and dotfiles are skipped by default, so plugin secrets do not leak into model context.

  • No network. The server makes no outbound network requests of its own.

  • No shell=True, no eval. Anywhere.

Development

pip install -e ".[dev]"
ruff check .
ruff format --check .
mypy
pytest

The test suite includes adversarial path-traversal tests (tests/test_pathing.py) — keep them green.

License

MIT

Available Tools

1 tool
get_noteA

Read a single note from the vault.

Args: path: Vault-relative POSIX path to a Markdown file (e.g. Topics/MCP.md).

Returns: The parsed note including frontmatter, tags, and outgoing wikilinks.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
pathYesVault-relative POSIX path, e.g. 'Topics/MCP.md'.
tagsNoInline #tags plus frontmatter tags.
titleYesDisplay title (frontmatter > first H1 > filename stem).
contentYesRaw Markdown body, without frontmatter.
truncatedNoTrue if the file was larger than max_file_kb and content is truncated.
size_bytesNo
frontmatterNo
modified_atNo
outgoing_linksNoTargets of [[wikilinks]].

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses input constraints (POSIX path, Markdown file) and output contents (frontmatter, tags, wikilinks). Does not cover error conditions, but this is acceptable for a simple read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: one sentence for purpose, then structured Args/Returns sections. Every sentence adds value with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, read-only tool with an output schema hinted, the description fully explains the parameter constraints and return fields, making it complete for correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must add meaning. It does so effectively by describing 'path' as a vault-relative POSIX path to a Markdown file with an example, far exceeding the minimal schema type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read a single note from the vault.' using a specific verb and resource. No sibling tools exist, so distinction is not required.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when you need to read a specific note. However, no explicit when-not-to-use or alternative tools are mentioned, which is acceptable given no siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedget_note
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of confusion between tools. The tool's purpose is clear and distinct.

Naming Consistency5/5

With a single tool, naming consistency is not a concern; the name follows a clear verb_noun pattern that matches common conventions.

Tool Count2/5

A single tool for an Obsidian vault MCP is insufficient. Typical vault operations (list, create, update, delete) are missing, making the count too few for the apparent scope.

Completeness1/5

The server severely lacks coverage. Only reading a note is supported; essential operations like listing, creating, updating, and deleting notes are absent, making it incomplete for a note management domain.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Obsidian MCP Tool Server

    Rwb3n
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides an MCP server that allows AI assistants to interact with Obsidian vaults, enabling reading/writing notes, managing metadata, searching content, and working with daily notes.
    37
    MIT

  • Recalla

    Tensorboyalive
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to read and search your Obsidian vault through a local MCP server, keeping everything private and local.
    Apache 2.0