Vault Graph

MIT License Node Version TypeScript

🧠 AI-powered knowledge graph navigation for Obsidian vaults

An MCP (Model Context Protocol) server for Obsidian vault graph navigation and ranking. Provides AI agents with structured access to your knowledge graph.

Why Vault Graph MCP?

For AI Agents & Personal Knowledge Management:

• 🤖 Give AI agents context-aware access to your Obsidian vault without exposing raw file contents
• 🔗 Discover connections you didn't know existed through 2-hop relationship analysis
• 🎯 Smart recommendations based on graph structure, not just keyword matching
• 📊 Identify knowledge hubs to understand which concepts are central to your thinking
• 🧭 Navigate semantically using tag overlap and shared neighbor relationships
• ⚡ Fast & cached - millisecond-level queries even on large vaults (1000+ notes)

Use Cases:

• Ask Claude "What should I read next after this note on Kubernetes?"
• Find thematically related notes even when not directly linked
• Discover central concepts and knowledge clusters in your vault
• Get AI-powered note recommendations based on graph topology
• Explore your knowledge graph through natural language queries

Features

• Graph Navigation: Traverse links between notes
• Ranked Recommendations: Get relevant note suggestions based on shared neighbors, in-degree, and tag overlap
• Hub Discovery: Find central concepts in your vault
• 2-Hop Related: Discover notes connected through intermediate links
• Search: Find notes by title or tags
• Loki-Compatible Logging: Structured JSON logs for observability

Installation

npm install
npm run build

Usage

1. Via .mcp.json (Claude Code Projects)

Create a .mcp.json file in your project root. Claude Code automatically loads this file when starting in the directory.

If your working directory is your Obsidian vault, no VAULT_PATH is needed — the server auto-detects it from MCP roots:

{
  "mcpServers": {
    "vault-graph": {
      "command": "node",
      "args": ["/path/to/vault-graph-mcp/dist/index.js"]
    }
  }
}

If your vault is elsewhere, set VAULT_PATH explicitly:

{
  "mcpServers": {
    "vault-graph": {
      "command": "node",
      "args": ["/path/to/vault-graph-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Note: .mcp.json is currently only supported by Claude Code. Gemini CLI uses .gemini/settings.json and Codex CLI uses .codex/config.toml for project-level configuration (see sections below).

2. Via Claude CLI

Use the Claude CLI to install directly:

# Build the project first
npm run build

# Add the MCP server via CLI
claude mcp add --transport stdio \
  --env VAULT_PATH=/path/to/your/obsidian/vault \
  vault-graph -- node /path/to/vault-graph-mcp/dist/index.js

# List installed servers
claude mcp list

# Remove if needed
claude mcp remove vault-graph

Note: All options (--transport, --env, --scope) must come before the server name. The -- separates the server name from the command and arguments.

See Claude CLI MCP documentation for more details.

3. With Claude Desktop (Global)

Add to your Claude Desktop configuration:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vault-graph": {
      "command": "node",
      "args": ["/path/to/vault-graph-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

4. With Gemini CLI

Add to your Gemini CLI settings at ~/.gemini/settings.json:

{
  "mcpServers": {
    "vault-graph": {
      "command": "node",
      "args": ["/path/to/vault-graph-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Or use the CLI:

gemini mcp add vault-graph -- node /path/to/vault-graph-mcp/dist/index.js

See Gemini CLI MCP documentation for more details.

5. With Codex CLI (OpenAI)

Add to your Codex configuration at ~/.codex/config.toml:

[mcp_servers.vault-graph]
command = "node"
args = ["/path/to/vault-graph-mcp/dist/index.js"]

[mcp_servers.vault-graph.env]
VAULT_PATH = "/path/to/your/obsidian/vault"

Or use the CLI:

codex mcp add vault-graph --env VAULT_PATH=/path/to/your/obsidian/vault \
  -- node /path/to/vault-graph-mcp/dist/index.js

See Codex MCP documentation for more details.

6. Standalone

VAULT_PATH=/path/to/vault npm start

7. Development

VAULT_PATH=./test/vault npm run dev

MCP Support in Different AI Systems

✅ Claude (Anthropic)

• Claude Desktop: Full support via config file
• Claude Code: Full support with claude mcp add command and .mcp.json

✅ Gemini (Google)

• Gemini CLI: Full support via settings.json or gemini mcp add command

✅ Codex (OpenAI)

• Codex CLI: Full support via config.toml or codex mcp add command

Note: MCP is an open standard, so support continues to expand. Check your AI platform's documentation for the latest MCP capabilities.

Configuration

Vault Path Resolution

VAULT_PATH is optional. The server resolves the vault path in this order:

1. VAULT_PATH environment variable — if set, used directly (backwards compatible)
2. MCP client roots — if the client supports roots, the server uses the first file:// root as the vault path

This means MCP clients like Claude Code, which expose the working directory as a root, work with zero configuration when launched from inside an Obsidian vault.

If neither source provides a vault path, the server exits with a descriptive error.

Environment Variables

Environment Variable	Description	Default
VAULT_PATH	Path to Obsidian vault (auto-detected from MCP roots if omitted)	-
VAULT_GRAPH_INCLUDE_GLOBS	Comma-separated include patterns	**/*.md
VAULT_GRAPH_EXCLUDE_GLOBS	Comma-separated exclude patterns	.obsidian/**,.trash/**
VAULT_GRAPH_CACHE_DIR	Cache directory (relative to vault)	.mcp-cache
VAULT_GRAPH_LOG_LEVEL	Log level: debug, info, warn, error	info
VAULT_GRAPH_JSON_LOGS	Output JSON logs (for Loki)	true

MCP Tools

graph_build_index

Rebuild the vault graph index.

{
  "force": true  // Force rebuild even if cache is valid
}

graph_get_neighbors

Get all neighbors (linked notes) for a node.

{
  "node": "DevOps/GitOps.md",
  "direction": "out"  // "in", "out", or "both"
}

graph_get_neighbors_ranked

Get neighbors ranked by relevance with explanations.

{
  "node": "DevOps/GitOps.md",
  "direction": "out",
  "limit": 10,
  "weights": {
    "commonNeighbors": 0.55,
    "degree": 0.35,
    "tagOverlap": 0.10
  }
}

Response:

{
  "node": "DevOps/GitOps.md",
  "direction": "out",
  "results": [
    {
      "id": "DevOps/FluxCD.md",
      "title": "FluxCD",
      "score": 0.72,
      "reasons": [
        "3 shared neighbors",
        "high in-degree (5)",
        "tag overlap: devops, gitops"
      ]
    }
  ],
  "count": 5
}

graph_related

Find related notes that are 2 hops away (not directly linked).

{
  "node": "DevOps/GitOps.md",
  "limit": 10,
  "direction": "out"
}

graph_hubs

Find the most connected notes (central concepts).

{
  "limit": 10,
  "mode": "in"  // "in" (most referenced), "out" (most linking), "both"
}

graph_search

Search for notes by title or tags.

{
  "query": "kubernetes",
  "limit": 20,
  "searchIn": ["title", "tags"]
}

graph_get_node

Get detailed information about a specific node.

{
  "node": "DevOps/GitOps.md"
}

MCP Resources

vault://node/{id}

Get information about a specific node.

vault://graph

Get the full vault graph (paginated). Supports query parameters:

• page: Page number (default: 1)
• pageSize: Results per page (default: 100)

vault://stats

Get vault statistics: node count, edge count, top hubs, etc.

vault://metrics

Get server performance metrics (Loki-compatible).

Ranking Algorithm

The ranking engine uses a weighted combination of three factors:

Factor	Weight	Description
Common Neighbors	0.55	Nodes that share connections tend to be thematically related
In-Degree	0.35	Highly referenced nodes are important concepts
Tag Overlap	0.10	Shared tags indicate semantic similarity

Score Formula:

score = 0.55 * commonNeighborsNorm + 0.35 * degreeNorm + 0.10 * tagJaccard

All components are normalized to [0, 1].

Logging

Logs are output in JSON format for Loki compatibility:

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "level": "info",
  "component": "graph.builder",
  "event": "build_complete",
  "vault": "/path/to/vault",
  "nodeCount": 842,
  "edgeCount": 3421,
  "duration_ms": 312
}

Loki Integration

Ship logs to Loki via:

• Promtail: Tail stdout logs
• Docker logging driver: Configure JSON logging

Recommended labels:

• app=vault-graph-mcp
• component={component}

Performance

Operation	Target	Typical
Full index (1k files)	< 1s	~300ms
Ranked neighbors	< 50ms	~5ms
Related (2-hop)	< 150ms	~15ms

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build
npm run build

# Lint
npm run lint

# Type check
npm run typecheck

Project Structure

vault-graph-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── types.ts              # Type definitions
│   ├── config.ts             # Configuration loader
│   ├── scanner/              # Vault file scanner
│   ├── parser/               # Markdown parser
│   ├── graph/                # Graph index & cache
│   ├── ranking/              # Ranking engine
│   ├── server/               # MCP server & handlers
│   └── logger/               # Logging & metrics
├── test/
│   ├── vault/                # Test vault
│   └── *.test.ts             # Test files
└── dist/                     # Compiled output

License

MIT