dot-RealityTest/obsidian-codex-mcp

Local-first MCP server for working with an Obsidian vault.
- No Obsidian plugin required
- No API key required
- No cloud service required
- No Obsidian running in the background
This is for people who want MCP clients to work directly with markdown files on disk.
> Independent open-source project. Not affiliated with Obsidian, Anthropic, OpenAI, or any MCP client.
What it does
It lets MCP clients work with your vault to:
- read and search notes
- create and update notes
- create and edit Obsidian Bases (.base files) with schema validation
- generate summaries, status reports, and release notes
- automate local knowledge workflows
All directly against your local markdown files.
Best for
- Anyone using an MCP client — Claude Code, Claude Desktop, Cursor, Cline, Codex, Grok — who wants safe local access to an Obsidian vault
- Developers who prefer filesystem-based Obsidian automation over the Local REST API plugin
- People who want to create and edit Obsidian Bases (.base) from an agent
- Personal knowledge bases, project logs, daily notes, task notes, and markdown-first workflows
Why this exists
There are already a handful of Obsidian MCP servers. Many depend on the Obsidian Local REST API plugin or run as an Obsidian plugin. This project is intentionally simpler:
- direct filesystem access to a local vault
- no network calls
- no Obsidian API token
- works with any MCP client — simple JSON or TOML config for Claude Code, Claude Desktop, Cursor, Cline, Codex, and Grok
- tolerant of real-world vaults with imperfect frontmatter
- path traversal protection so tools cannot escape the configured vault
- optional read-only mode for safer review/search workflows
- optional backup-on-write before updates and deletes
- **first-class Obsidian Bases (.base) support with schema validation** — a differentiator: almost no other Obsidian MCP server can create or edit Bases, and this one validates them against the official schema so it never writes a file Obsidian would silently reject
How it compares
| Need | This project |
| --- | --- |
| Use Obsidian with any MCP client | Yes — Claude Code, Claude Desktop, Cursor, Cline, Codex, Grok |
| Config format | JSON or TOML, per client (examples for each) |
| Require an Obsidian plugin | No |
| Require an API key | No |
| Require Obsidian to be open | No |
| Read/write markdown files directly | Yes |
| Create and edit Obsidian Bases (.base) | Yes, with schema validation |
| Work over a remote HTTP API | No, local stdio MCP only |
Safety features
Designed to be useful without being reckless:
- read-only mode, which refuses writes
- backup-on-write mode before updates and deletes
- vault path isolation
- path traversal protection
- no external network calls
Tools
- configure_vault - set or change the vault path
- get_note - read one markdown note by vault-relative path
- create_note - create a new markdown note with optional metadata
- update_note - update note content and/or frontmatter
- delete_note - delete a markdown note
- list_notes - list notes in the vault or a folder
- search_notes - search note title, content, and tags
- get_all_tags - list unique tags from frontmatter and inline tags
- get_backlinks - find notes that link to a note
- get_note_links - extract wikilinks from a note
- create_folder - create a folder inside the vault
- get_folder_structure - return the vault folder tree
Bases (.base files)
First-class, schema-validated support for Obsidian Bases — database-like views over your notes. Very few Obsidian MCP servers support these.
- create_base - create a .base file, validated against the Bases schema before writing
- update_base - merge changes into a base (update a view by name, add/remove views, change filters/formulas/properties)