# mcp-obsidian

*🇬🇧 English · [🇫🇷 Français](README.fr.md)*

A **filesystem-based** [MCP](https://modelcontextprotocol.io) server for an
[Obsidian](https://obsidian.md) vault. It reads and writes your vault's
Markdown files **directly on disk** — no Obsidian plugin, no Local REST API, no
running Obsidian instance required. Point it at a folder and your LLM can browse
and edit notes.

## Why filesystem-based

Most Obsidian MCP servers talk to the *Local REST API* community plugin, which
means Obsidian must be running with the plugin enabled. `mcp-obsidian` skips all
that and operates on the vault directory itself — works headless, in CI, or on a
synced folder.

## Tools

| Tool | Description |
|------|-------------|
| `obsidian_read` | Read a note (with optional truncation) |
| `obsidian_search` | Keyword search across notes, with truncated context per hit; optional subfolder scope |
| `obsidian_write` | Create or overwrite a note (creates parent folders) |
| `obsidian_append` | Append content to a note |
| `obsidian_patch_frontmatter` | Patch a note's YAML frontmatter |
| `obsidian_list` | List `.md` files and subfolders of a directory |

All paths are **relative to the vault root** (e.g. `wiki/cyber/sql-injection.md`).

### Scope

This server is **transport only**. It has no notion of a "claim", no conflict
detection and no merge policy — `obsidian_write` is a plain overwrite, last write
wins. Contradiction handling, note conventions and the human-in-the-loop review
step live one layer up, in
[claude-obsidian-system](https://github.com/NeveuGregor/claude-obsidian-system).

## Install

```bash
git clone https://github.com/NeveuGregor/mcp-obsidian.git
cd mcp-obsidian
npm install
npm run build      # compiles TypeScript to dist/
```

## Configuration

The vault path is provided via the `OBSIDIAN_VAULT` environment variable
(absolute path). The server exits with an error if it is not set.

Register it with Claude (CLI or Desktop), e.g. in your MCP config:

```json
{
  "mcpServers": {
    "obsidian": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-obsidian/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT": "/absolute/path/to/your/vault"
      }
    }
  }
}
```

## Requirements

- Node.js 18+
- An Obsidian vault (just a folder of Markdown files)

## Related

This server is the *MCP layer* of a broader knowledge architecture —
**[claude-obsidian-system](https://github.com/NeveuGregor/claude-obsidian-system)** —
which documents how the vault itself is designed (LLM-Wiki + Zettelkasten +
Evergreen) and wired to Claude Code skills and memory.

## License

[CeCILL-B](LICENSE) (BSD-compatible, French law) — © 2026 Neveu Grégor.