# Obsidian MCP Server

Have been using obsidian for quite awhile (have years and years of notes in my vault) and thought 
we could benefit from some kind of MCP server. 

This can be used to read notes from your vault, have AI agents create notes, etc.

Will periodically add more tools and enhancements to this...

Note: This is meant to be used locally or hosted yourself for now. This MCP server currently does not come with an AKS
deployment or anything like that. Your vault should ideally also be local (unless you're using some weird plugin),
so don't see this as a serious downside.

## Setup

### Install dependencies

Requires [uv](https://docs.astral.sh/uv/). Clone the repo, then:

```bash

# Install runtime dependencies
uv sync -p $(cat ./.python-version)

# Install with test extras
uv sync --extra test

# Install with dev extras
uv sync --extra dev

# Run tests
uv run pytest

# Run the server directly
uv run python -m obsidian_mcp.main
```

The virtual environment is created automatically by `uv` inside `.venv/`. Use `.venv/bin/python` as the interpreter path in your MCP client config.

### MCP client config

```json
{
   "mcpServers":{
      "obsidian_mcp":{
         "command":"/<path_to_project>/.venv/bin/python",
         "args": ["-m", "obsidian_mcp.main"],
         "env":{
            "OBSIDIAN_VAULT__PATH": "<local vault path>",
            "OBSIDIAN_VAULT__ATTACHMENT_PATH": "<path to attachments folder>",
            "OBSIDIAN_LOGGING__LEVEL": "INFO",
            "OBSIDIAN_LOGGING__FORMAT": "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
            "OBSIDIAN_SERVER__HOST": "127.0.0.1",
            "OBSIDIAN_SERVER__PORT": 8000,
            "OBSIDIAN_VAULT__ENABLE_WIKILINKS": "True",
            "OBSIDIAN_VAULT__ENABLE_FRONTMATTER": "True",
            "OBSIDIAN_SEARCH__ENABLED": "True",
            "OBSIDIAN_SEARCH__MAX_RESULTS": 100
         }
      }
   }
}
```
Note: If you have `<project_dir>/.env` file populated. You can remove these entries in the mcp config. The config class should load the
`.env`.

## Tools

### Notes

| Tool | Description |
|------|-------------|
| `list_notes` | List all notes in the vault or a subdirectory. Optionally exclude `.obsidian/` and `.trash/` (both excluded by default). |
| `get_note` | Read a note by its vault-relative path. Returns path, title, tags, frontmatter, and body. |
| `search_notes` | Search notes for a literal query string. Supports case sensitivity, frontmatter inclusion, and excluding `.obsidian/`/`.trash/`. |
| `create_note` | Create a new note at a given vault-relative path with optional YAML frontmatter. |
| `append_to_note` | Append text to the end of an existing note without overwriting it. |
| `update_note` | Overwrite the body of an existing note, optionally replacing its frontmatter. |
| `update_frontmatter` | Merge-patch specific frontmatter keys without rewriting the note body. Set a key to `null` to delete it. |
| `delete_note` | Delete a note by moving it to `.trash/` (default) or permanently removing it. |
| `move_note` | Move or rename a note and update all vault wikilinks that reference it. |

### Graph & Links

| Tool | Description |
|------|-------------|
| `get_links` | Return all outgoing wikilink targets from a note's body. |
| `get_backlinks` | Return all notes in the vault that contain a wikilink pointing to the given note. |
| `get_note_graph` | Return the full vault link graph as nodes and edges. Scoped to a subdirectory when `relative_path` is provided. |
| `find_broken_links` | Scan the vault for wikilinks that point to non-existent notes. |
| `find_orphans` | Return all notes that have no incoming wikilinks from other notes. |

### Tags & Metadata

| Tool | Description |
|------|-------------|
| `list_tags` | List all unique tags across the vault. Optionally include per-tag note counts. |
| `get_notes_by_tag` | Return all notes that contain a given tag (frontmatter or inline). |
| `search_by_tag` | Return notes matching any (or all) of a list of tags. |

### Vault

| Tool | Description |
|------|-------------|
| `get_vault_stats` | Return a snapshot of vault-level statistics: note count, folder count, unique tags, broken links, orphans, and attachment counts (when attachment path is configured). |
| `list_folders` | List all subdirectory paths within the vault or a given sub-path. |

### Attachments

> Requires `OBSIDIAN_VAULT__ATTACHMENT_PATH` to be set in your MCP config.

| Tool | Description |
|------|-------------|
| `list_attachments` | List all attachment files under the attachment root or a subdirectory. Returns path, name, suffix, and size for each file. |
| `get_attachment_info` | Return metadata for a single attachment file by its path relative to the attachment root. |
| `find_unused_attachments` | Return all attachments not referenced by any note in the vault (checks both wikilinks and markdown links). |

## Prompts

| Prompt | Description |
|--------|-------------|
| `summarize_note` | Fetches a note by path and returns a structured prompt asking the LLM for a TL;DR, key-point bullets, and any action items or decisions. |
| `clean_up_attachments` | Given a list of unused attachment paths, returns a prompt guiding the LLM to help decide which files to keep or delete. |