Obsidian Readonly

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.

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.