Obsidian Readonly MCP

Read-only MCP tools for querying a running Obsidian vault from Codex or another agentic runtime.

Why this exists

The Obsidian CLI is not just a filesystem reader; it is connected to your main Obsidian app. Commands such as backlinks, links, outline, and indexed search need to talk to the running Obsidian app. In agentic runtimes, the agent's filesystem sandbox can block or destabilize that app/IPC boundary. For example, running obsidian help inside an agent sandbox can cause the Obsidian app to crash.

Giving the whole agent unsandboxed shell access fixes the IPC problem, but it gives the agent too much permission. This MCP server is the narrower solution:

sandboxed agent
  -> read-only MCP tool call
  -> host-side MCP server
  -> obsidian CLI
  -> running Obsidian app

The agent can stay sandboxed. The host-side MCP server gets permission to reach Obsidian, but it exposes only a fixed allowlist of read-only Obsidian commands.

Related MCP server: obsidian-local-mcp-server

Safety model

This server:

• exposes only read-only Obsidian operations

• rejects unknown tools

• validates vault-relative paths and rejects .. path traversal

• builds obsidian argv directly without shell interpolation

• caps output size

• times out long calls

It does not expose:

• note creation or editing

• delete, move, rename, append, prepend

• property mutation

• plugin/theme install, enable, disable, reload, uninstall

• obsidian command

• obsidian eval

• app reload/restart/open/tab/workspace mutation

• browser/web/open actions

Feel free to modify it to add these features if you need them.

Tools

Core vault reads:

• search

• search_context

• read

• daily_read

• daily_path

• backlinks

• links

• outline

• aliases

• tags

• tag

• unresolved

• properties

• property_read

• help

Filesystem/index reads through Obsidian:

• file

• files

• folder

• folders

• wordcount

• deadends

• orphans

• recents

• random_read

• vault

• vaults

• version

Structured features:

• bases

• base_query

• base_views

• bookmarks

• tasks

• templates

• template_read

• snippets

• snippets_enabled

History/config metadata reads:

• diff

• history

• history_list

• history_read

• hotkey

• hotkeys

• plugins

• plugin

• plugins_enabled

• theme

• themes

• tabs

• workspace

• workspaces

• commands

Developer read-only inspection:

• dev_console

• dev_errors

• dev_css

• dev_dom

Install With uvx

You can run the MCP server directly from GitHub without cloning the repo:

[mcp_servers.obsidian_readonly]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/eothL/obsidian-readonly-mcp",
  "obsidian-readonly-mcp"
]

[mcp_servers.obsidian_readonly.env]
OBSIDIAN_READONLY_VAULT = "Your Vault Name"

Use the Obsidian vault name, not the filesystem path. It should be the same value you would pass to obsidian vault="Your Vault Name" ....

If this package is later published to PyPI, the config can become:

[mcp_servers.obsidian_readonly]
command = "uvx"
args = ["obsidian-readonly-mcp"]

[mcp_servers.obsidian_readonly.env]
OBSIDIAN_READONLY_VAULT = "Your Vault Name"

Restart Codex or start a new thread so the MCP server is discovered.

Install From A Local Clone

Clone this repo somewhere stable, then add the MCP server to your Codex config:

[mcp_servers.obsidian_readonly]
command = "python3"
args = ["/absolute/path/to/obsidian-readonly-mcp/src/obsidian_readonly_mcp.py"]

[mcp_servers.obsidian_readonly.env]
OBSIDIAN_READONLY_VAULT = "Your Vault Name"

Restart Codex or start a new thread so the MCP server is discovered.

Codex Plugin

This repository also includes Codex plugin metadata:

• .codex-plugin/plugin.json

• .mcp.json

• skills/obsidian-readonly-mcp/SKILL.md

The plugin bundles the MCP server and the companion skill so Codex can learn to prefer the read-only Obsidian tools for vault exploration. The plugin MCP config does not hard-code a vault name; set OBSIDIAN_READONLY_VAULT in your environment or pass the vault argument in tool calls.

Usage

Once loaded, tools are exposed as names such as:

mcp__obsidian_readonly__search
mcp__obsidian_readonly__read
mcp__obsidian_readonly__backlinks
mcp__obsidian_readonly__links
mcp__obsidian_readonly__outline

Example tool arguments:

{"query": "agent harness memory", "limit": 10}

{"file": "Agent harness memory", "counts": true, "format": "json"}

Local smoke test

With Obsidian open:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | python3 src/obsidian_readonly_mcp.py

End-to-end read:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"agent harness","limit":3}}}' \
  | python3 src/obsidian_readonly_mcp.py

Companion Skill

This repo includes a Codex skill in skills/obsidian-readonly-mcp/. Install or copy that skill into your Codex skills directory if you want agents to automatically prefer these tools for Obsidian vault exploration.

Read-only diagnostics and timeouts

The read-only server writes local JSON-line diagnostic logs. MCP stdout remains reserved for protocol responses. Events record request receipt, command start, command completion or timeout, cleanup, and response delivery, linked by an internally generated trace ID. Logs include timestamps, server PID, tool name, exit code, elapsed milliseconds, and output byte counts. They exclude request IDs, arguments, vault/note paths, queries, note contents, and raw stdout/stderr. Raw stderr remains available in the tool response as before; it is not persisted to logs. This protects diagnostic logs but does not anonymize tool results.

On macOS, logs are in ~/Library/Logs/obsidian-readonly-mcp/server.log. Elsewhere they are in $XDG_STATE_HOME/obsidian-readonly-mcp/server.log, falling back to ~/.local/state/obsidian-readonly-mcp/server.log. Logs rotate at 5 MiB, keeping the current file and two backups (about 15 MiB total). New directories are private and log files use mode 0600. Use a separate log directory for each concurrently running server instance; rotation is intended for one writer. A log setup failure reports a generic warning on stderr and does not prevent serving requests. Logging adds no dependencies.

Call health with {} or {"vault":"Your Vault Name"} to check both the server and an actual vault command (vault info=name). It returns responsiveness, elapsed time and the configured timeout, with isError when the probe fails. This checks the app connection, not just whether the CLI executable exists. A failed probe does not by itself distinguish a closed app from an IPC failure. MCP ping checks only the server.

On POSIX, timed-out CLI commands and helpers in their dedicated process group are killed. Pipe cleanup has its own one-second limit, avoiding an unbounded wait when a helper retains output pipes. The running Obsidian app is not targeted. On other platforms, only the direct CLI process is killed. Requests are handled serially, so concurrent client calls can queue behind an active command; the command timeout begins when that command is launched.

To investigate a delay, inspect the last event for a trace: command_started without completion points to the CLI/app boundary; command_timeout confirms the server timeout fired; response_sent means the response was flushed to the client transport. No request_received event suggests checking startup or the client connection (also verify logging is enabled and writable).

After modifying this repository, restart the MCP process using this checkout. A server configured to run a separate copied script does not pick up these changes automatically. The changes do not explain past hangs without diagnostic evidence.

Diagnostics and workflow regression tests run without Obsidian:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest discover -s tests -v

Bounded retrieval and batches

read accepts either heading (exact ATX Markdown heading text without the leading #, including subsections), or start_line / end_line (1-based, inclusive). Full reads are unchanged. Use outline to discover headings and search_context to find line numbers. Duplicate headings require a line range. Setext headings are not matched by heading; use a line range for those. Fenced code and YAML frontmatter are excluded from heading matching. The MCP still fetches the note through Obsidian and filters it before returning it; it does not cache notes or fall back to disk. A truncated source is rejected for partial reads rather than silently returning an incomplete section.

{"path":"Notes/GPU.md","heading":"Memory hierarchy"}

{"path":"Notes/GPU.md","start_line":20,"end_line":50}

batch accepts 1–8 independent read-only calls. Results retain input order and have individual isError flags. It runs commands sequentially under one shared command timeout and output budget; nesting and unknown tools are rejected. Arguments (including vault when supported) belong on each child call. Budget exhaustion returns explicit errors for omitted results. Prefer narrow searches and selected sections over batching many full documents. Batching reduces MCP call overhead, not the number of underlying CLI operations by itself.

{"calls":[{"tool":"outline","arguments":{"path":"Notes/GPU.md"}},{"tool":"links","arguments":{"path":"Notes/GPU.md"}}]}

The runtime exposes run_command and main(request_handler) so a project adapter can retain stricter schemas and a pinned vault while reusing logging and timeout fixes. Updating a repository checkout affects new server processes; already running servers must restart. Detached script copies do not update automatically.

Protocol compatibility

This server uses local stdio and the legacy initialize handshake. It does not store conversation history or note caches, but it has not implemented the modern 2026-07-28 stateless wire protocol (server/discover and per-request metadata). Initialization negotiates a supported legacy version instead of echoing an unsupported modern version. No HTTP endpoint or session service is introduced.

Evaluating real tool use

Unit tests verify correctness; they cannot establish whether an agent chooses a tool or produces a better answer. Use a fresh, read-only agent session with a fixed task/model and codex exec --json, keeping the prompt independent of the feature being evaluated. Save traces outside the repo: they contain private note contents. Run the same prompt with baseline and candidate tool catalogs, then:

python3 scripts/summarize_trace.py /path/to/run.jsonl --server-log /path/to/server.log

The summary excludes note text and arguments. Compare logical operations as well as MCP calls, partial-read use, output size, budget/error events, cached versus uncached input tokens, and a manually scored answer-quality rubric. Repeat tasks before claiming stable savings. Suggested fixtures: a short note, a long lecture with relevant subsections, ambiguous headings, a missing note, a timeout, and a large search response. Check that conclusions remain supported, contradictory notes are noticed, and missing/error results are not treated as evidence.

Failure cooldown

After two consecutive infrastructure failures for the same vault, commands return an immediate tool error with status: cooldown and retry_after_seconds. The process does not sleep or launch more CLI subprocesses during the pause, including for children of a batch. OBSIDIAN_READONLY_COOLDOWN_SECONDS defaults to 60; set it to 0 to disable. Counters are process-local, per vault, and bounded to 64 vault entries. Expiry permits another attempt; successful execution clears the failure streak. A deliberate health call bypasses the pause and clears it if successful. Repeated health polling defeats this protection.

Launch failures, command timeouts and infrastructure command errors count. Input validation failures and recognized missing-file/folder/property/heading responses do not. No missing note is treated as proof that the Obsidian app is broken. Cooldown state contains no note data or conversation history; it is operational health state, compatible with a future stateless protocol implementation.

The MCP always executes the Obsidian CLI directly (argv, no shell). It does not replace failures with Bash commands, direct .md reads, or cached notes. The companion skills likewise instruct agents to report unavailability and respect the retry interval instead of falling back to direct filesystem retrieval.