# Obsidian MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes an Obsidian vault as a structured interface for AI models. Connect Claude Desktop or Claude Code to your vault and interact with your notes in natural language.

## What it does

Instead of manually navigating your vault, you can ask Claude:

- *"Read my weekly plan for W31"*
- *"Search my notes for anything about HireRight"*
- *"What are my 5 most recently modified notes?"*
- *"What's the structure of my vault?"*
- *"Create today's daily note"*

Claude calls the appropriate tool, reads or writes the file, and responds naturally.

## Tools

| Tool | Description |
|------|-------------|
| `read_note(path)` | Read a note by path relative to vault root |
| `list_recent(n)` | List the N most recently modified notes |
| `search_vault(query, tag, folder)` | Full-text search with optional tag and folder filters |
| `get_vault_structure()` | Get the folder hierarchy and note counts |
| `create_note(path, content)` | Create a new note (refuses to overwrite existing) |

## Architecture

```
Claude Desktop / Claude Code
        │
        │  stdio (local)
        ▼
  MCP Server (server.py)
        │
        ▼
  Obsidian Vault (filesystem)
```

The server runs as a local process started by the MCP host (Claude Desktop or Claude Code). Communication happens over stdio — no network exposure, no auth required for local use.

## Stack

- Python 3.10+
- [mcp](https://github.com/modelcontextprotocol/python-sdk) 2.0.0 — official MCP Python SDK
- [uv](https://github.com/astral-sh/uv) — package manager

## Setup

**1. Clone and install dependencies**

```bash
git clone https://github.com/DusanMilic/obsidian-mcp-server.git
cd obsidian-mcp-server
uv sync
```

**2. Set your vault path**

Edit `server.py` and update `VAULT_PATH`:

```python
VAULT_PATH = Path("/your/path/to/obsidian/vault")
```

**3. Connect to Claude Desktop**

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/uv",
      "args": [
        "--directory", "/path/to/obsidian-mcp-server",
        "run", "server.py"
      ]
    }
  }
}
```

Restart Claude Desktop. The server starts automatically.

**4. Connect to Claude Code**

```bash
claude mcp add --scope user obsidian -- /path/to/uv --directory /path/to/obsidian-mcp-server run server.py
```

## Security

- All paths are validated to be within the vault root — no path traversal possible
- `create_note` refuses to overwrite existing notes
- No write tool overwrites existing content — `create_note` is append-safe by design
- Local stdio transport only — no network exposure in default configuration

## Project context

Built as Phase 1 of an AI engineering learning path — the goal is to move from AI consumer to AI builder. This server is used daily to give Claude structured access to a personal Obsidian vault containing journaling, planning, and project notes.

Phase 2 will extend this into a personal finance agent. Phase 4 targets a real estate agentic analyzer over Serbian property data.