# obsidian-mcp

A small [Model Context Protocol](https://modelcontextprotocol.io) server that gives
an MCP client (such as Claude Code or Claude Desktop) read and write access to an
[Obsidian](https://obsidian.md) vault by working directly on the markdown files.

No Obsidian plugins required and the app does not need to be running — the server
reads and writes the `.md` files on disk.

## Features

- Works directly on the vault's files (no Local REST API plugin needed).
- Path-traversal safe: every path is resolved inside the vault; `../` escapes are rejected.
- Ignores `.obsidian`, `.git`, `.trash` and `node_modules`.

### Tools

| Tool | Description |
|------|-------------|
| `search_notes` | Full-text search across all notes, with line snippets |
| `list_notes` | List notes in the whole vault or a subfolder |
| `read_note` | Read a note by its vault-relative path |
| `create_note` | Create a new note (creates folders; won't overwrite unless asked) |
| `edit_note` | Replace an exact string in a note (`replace_all` optional) |
| `append_note` | Append text to the end of a note |

## Requirements

- Node.js >= 18

## Installation

```bash
git clone https://github.com/C0d1g0v3c/obsidian-mcp.git
cd obsidian-mcp
npm install
```

## Configuration

The server requires the `OBSIDIAN_VAULT` environment variable: the absolute path
to your vault. It exits with an error if it is not set.

## Usage with Claude Code

```bash
claude mcp add obsidian --scope user \
  -e OBSIDIAN_VAULT="/absolute/path/to/your/vault" \
  -- node /absolute/path/to/obsidian-mcp/index.js
```

## Usage with Claude Desktop

Add this to your `claude_desktop_config.json`:

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

## Running directly

```bash
OBSIDIAN_VAULT="/absolute/path/to/your/vault" node index.js
```

The server communicates over stdio and is meant to be launched by an MCP client.

## License

ISC