Vault Graph MCP Server

🧠 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:

VAULT_PATH environment variable — if set, used directly (backwards compatible)
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

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
src		src
test		test
.editorconfig		.editorconfig
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierrc		.prettierrc
CONTRIBUTING.md		CONTRIBUTING.md
IMPLEMENTATION.md		IMPLEMENTATION.md
LICENSE		LICENSE
PLAN.md		PLAN.md
README.md		README.md
TEST_VAULT.md		TEST_VAULT.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

pascalweiss/vault-graph-mcp

Folders and files

Latest commit

History

Repository files navigation

Vault Graph MCP Server

Why Vault Graph MCP?

Features

Installation

Usage

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

2. Via Claude CLI

3. With Claude Desktop (Global)

4. With Gemini CLI

5. With Codex CLI (OpenAI)

6. Standalone

7. Development

MCP Support in Different AI Systems

✅ Claude (Anthropic)

✅ Gemini (Google)

✅ Codex (OpenAI)

Configuration

Vault Path Resolution

Environment Variables

MCP Tools

graph_build_index

graph_get_neighbors

graph_get_neighbors_ranked

graph_related

graph_hubs

graph_search

graph_get_node

MCP Resources

vault://node/{id}

vault://graph

vault://stats

vault://metrics

Ranking Algorithm

Logging

Loki Integration

Performance

Development

Project Structure

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

`graph_build_index`

`graph_get_neighbors`

`graph_get_neighbors_ranked`

`graph_related`

`graph_hubs`

`graph_search`

`graph_get_node`

`vault://node/{id}`

`vault://graph`

`vault://stats`

`vault://metrics`

Packages