https://github.com/tiim/obsidian-graph-mcp
MCP server to expose graph operations on notes in an obsidian vault.
https://github.com/tiim/obsidian-graph-mcp
Last synced: 4 days ago
JSON representation
MCP server to expose graph operations on notes in an obsidian vault.
- Host: GitHub
- URL: https://github.com/tiim/obsidian-graph-mcp
- Owner: Tiim
- Created: 2026-04-11T23:13:15.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-11T23:26:00.000Z (about 2 months ago)
- Last Synced: 2026-04-12T01:17:32.519Z (about 2 months ago)
- Language: Go
- Size: 28.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# obsidian-graph-mcp
An MCP (Model Context Protocol) server written in Go that analyzes the link graph of an [Obsidian](https://obsidian.md) vault. It also ships a small CLI for quick one-off queries.
## Features
- **Shortest path** between any two notes via BFS traversal
- **Linked notes** — outgoing and incoming links for a note
- **Orphaned notes** — notes with no links at all
- **Unreachable notes** — notes not reachable from a given starting note
- **Live graph** — file-system watcher keeps the internal note-graph up to date as you edit
- Supports wikilinks `[[Note]]`, embeds `![[Note]]`, and standard markdown links
## Requirements
- Go 1.25+
- An Obsidian vault (a directory containing `.obsidian/`)
## Installation
```bash
go install github.com/tiim/obsidian-graph-mcp@latest
```
Or build from source:
```bash
git clone https://github.com/tiim/obsidian-graph-mcp
cd obsidian-graph-mcp
go build -o obsidian-graph-mcp .
```
## Usage
```
obsidian-graph-mcp [flags] [args]
Commands:
mcp Start the MCP server (stdio transport)
shortest-path Shortest path between two notes
linked-notes Notes linked to/from a note
orphaned-notes Notes with no links
unreachable-notes Notes not reachable from a starting note
Flags:
--vault Path to the Obsidian vault (defaults to current directory)
--ignore Glob pattern, folder, or file to exclude (repeatable)
```
All note paths are **vault-relative** (e.g. `folder/My Note.md`).
### CLI examples
```bash
# Run from inside the vault
cd ~/Notes
obsidian-graph-mcp shortest-path "Daily/2024-01-01.md" "Projects/Big Idea.md"
# Specify vault explicitly
obsidian-graph-mcp --vault ~/Notes orphaned-notes
# Exclude folders
obsidian-graph-mcp --vault ~/Notes --ignore "Archive" --ignore "Templates" orphaned-notes
```
### MCP server
Start the server with the `mcp` command. It uses stdio transport (stdin/stdout), which is the standard for MCP clients.
```bash
obsidian-graph-mcp --vault ~/Notes mcp
```
#### Claude Desktop configuration
Add the server to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"obsidian-graph": {
"command": "obsidian-graph-mcp",
"args": ["--vault", "/path/to/your/vault", "--ignore", "Daily", "mcp"]
}
}
}
```
#### Claude Code configuration
```bash
claude mcp add obsidian-graph -- obsidian-graph-mcp --vault /path/to/your/vault mcp
```
## MCP tools
### `get_shortest_path`
Returns the shortest path between two notes. Each step includes the direction (`forward`/`backward`) and link type.
**Input:**
| Field | Type | Description |
|-------|--------|-------------|
| `from` | string | Vault-relative path of the starting note |
| `to` | string | Vault-relative path of the destination note |
**Example output:**
```json
[
{ "from": "Daily/2024-01-01.md", "to": "Projects/Big Idea.md", "direction": "forward", "type": "wikilink" },
{ "from": "Projects/Big Idea.md", "to": "People/Alice.md", "direction": "forward", "type": "wikilink" }
]
```
---
### `get_linked_notes`
Returns all notes a given note links to (outgoing) and all notes that link to it (incoming).
**Input:**
| Field | Type | Description |
|--------|--------|-------------|
| `note` | string | Vault-relative path of the note |
**Example output:**
```json
{
"links_to": [
{ "note": "Projects/Big Idea.md", "link_type": "wikilink" }
],
"linked_from": [
{ "note": "Daily/2024-01-02.md", "link_type": "wikilink" }
]
}
```
---
### `get_orphaned_notes`
Returns all real notes that have neither incoming nor outgoing links.
**Example output:**
```json
{
"orphans": ["Scratch/untitled.md", "inbox/random thought.md"]
}
```
---
### `get_unreachable_notes`
Returns all real notes that cannot be reached from the given starting note via any chain of links (traversal is undirected).
**Input:**
| Field | Type | Description |
|--------|--------|-------------|
| `from` | string | Vault-relative path of the starting note |
**Example output:**
```json
{
"from": "Home.md",
"unreachable": ["Archive/old-project.md", "Scratch/draft.md"]
}
```
## Development
```bash
go build ./... # Build
go test ./... # Run tests
go vet ./... # Lint
go mod tidy # Sync dependencies
```