graphthulhu

MCP server that gives AI full access to your knowledge graph. Supports Logseq and Obsidian — both with full read-write support. Navigate pages, search blocks, analyze link structure, track decisions, manage flashcards, and write content — all through the Model Context Protocol.

Built in Go with the official MCP Go SDK.

Why

Your knowledge graph stores interconnected pages, blocks, and links. But AI assistants can't see any of it — they're blind to your second brain.

graphthulhu fixes that. It exposes your entire knowledge graph through MCP, so Claude (or any MCP client) can:

• Read any page with its full block tree, parsed links, tags, and properties
• Search across all blocks with contextual results (parent chain + siblings)
• Traverse the link graph to discover how concepts connect
• Find knowledge gaps — orphan pages, dead ends, weakly-linked areas
• Discover topic clusters through connected component analysis
• Create pages, write blocks, build hierarchies, link pages bidirectionally (Logseq)
• Query with raw DataScript/Datalog for anything the built-in tools don't cover (Logseq)
• Review flashcards with spaced repetition statistics (Logseq)
• Explore whiteboards and their spatial connections (Logseq)

It turns "tell me about X" into an AI that actually understands your knowledge graph's structure.

Tools

37 tools across 9 categories. Most work with both backends; some are Logseq-only (DataScript queries, flashcards, whiteboards).

Navigate

| Tool | Backend | Description | |------|---------|-------------| | get_page | Both | Full recursive block tree with parsed links, tags, properties | | get_block | Both | Block by UUID with ancestor chain, children, siblings | | list_pages | Both | Filter by namespace, property, or tag; sort by name/modified/created | | get_links | Both | Forward and backward links with the blocks that contain them | | get_references | Logseq | All blocks referencing a specific block via ((uuid)) | | traverse | Both | BFS path-finding between two pages through the link graph |

Search

| Tool | Backend | Description | |------|---------|-------------| | search | Both | Full-text search with parent chain + sibling context | | query_properties | Both | Find by property values with operators (eq, contains, gt, lt) | | query_datalog | Logseq | Raw DataScript/Datalog queries against the Logseq database | | find_by_tag | Both | Tag search with child tag hierarchy support |

Analyze

| Tool | Backend | Description | |------|---------|-------------| | graph_overview | Both | Global stats: pages, blocks, links, most connected, namespaces | | find_connections | Both | Direct links, shortest paths, shared connections between pages | | knowledge_gaps | Both | Orphan pages, dead ends, weakly-linked areas | | list_orphans | Both | List orphan page names with block counts and property status | | topic_clusters | Both | Connected components with hub identification |

Write

| Tool | Backend | Description | |------|---------|-------------| | create_page | Both | New page with properties and initial blocks | | append_blocks | Both | Append plain-text blocks (simpler than upsert_blocks) | | upsert_blocks | Both | Batch create with nested children for deep hierarchies | | update_block | Both | Replace block content by UUID | | delete_block | Both | Remove block and all children | | move_block | Both | Reposition before, after, or as child of another block (cross-page supported) | | link_pages | Both | Bidirectional link with optional relationship context | | delete_page | Both | Remove a page and all its blocks | | rename_page | Both | Rename page and update all [[links]] across the graph | | bulk_update_properties | Both | Set a property on multiple pages in one call |

Decision

| Tool | Backend | Description | |------|---------|-------------| | decision_check | Both | Surface open, overdue, and resolved decisions with deadline status | | decision_create | Both | Create a DECIDE block with #decision tag, deadline, options, context | | decision_resolve | Both | Mark a decision as DONE with resolution date and outcome | | decision_defer | Both | Push deadline with reason, tracks deferral count, warns after 3+ | | analysis_health | Both | Audit analysis/strategy pages for graph connectivity (3+ links or has decision) |

Journal

| Tool | Backend | Description | |------|---------|-------------| | journal_range | Both | Entries across a date range with full block trees | | journal_search | Both | Search within journals, optionally filtered by date |

Flashcard

| Tool | Backend | Description | |------|---------|-------------| | flashcard_overview | Logseq | SRS stats: total, due, new vs reviewed, average repeats | | flashcard_due | Logseq | Cards due for review with ease factor and interval | | flashcard_create | Logseq | Create front/back card with #card tag |

Whiteboard

| Tool | Backend | Description | |------|---------|-------------| | list_whiteboards | Logseq | All whiteboards in the graph | | get_whiteboard | Logseq | Embedded pages, block references, visual connections |

Health

| Tool | Backend | Description | |------|---------|-------------| | health | Both | Check server status: version, backend, read-only mode, page count |

Install

Download binary

Grab the latest release for your platform from GitHub Releases and add it to your PATH.

go install

go install github.com/skridlevsky/graphthulhu@latest

Build from source

git clone https://github.com/skridlevsky/graphthulhu.git
cd graphthulhu
go build -o graphthulhu .

Setup: Logseq

1. In Logseq, go to Settings → Features and enable HTTP APIs server
2. Click the API icon that appears in the top toolbar
3. Click Start Server
4. Click Create Token and copy the generated token — you'll need it for configuration

The API runs on http://127.0.0.1:12315 by default.

Setup: Obsidian

No plugins or server required. graphthulhu reads your vault's .md files directly.

You need to provide the path to your vault:

graphthulhu serve --backend obsidian --vault /path/to/your/vault

Or via environment variables:

export GRAPHTHULHU_BACKEND=obsidian
export OBSIDIAN_VAULT_PATH=/path/to/your/vault
graphthulhu

The Obsidian backend supports full read-write operations. It parses YAML frontmatter into properties, builds a block tree from headings, and indexes [[wikilinks]] for backlink resolution. Writes use atomic temp-file renames, and the in-memory index is rebuilt after every mutation. File watching (fsnotify) keeps the index in sync with external edits. Daily notes are detected from a configurable subfolder (default: daily notes).

Configuration

Logseq — Claude Code

Add to your MCP settings (~/.claude/claude_code_config.json or project-level .claude/settings.json):

{
  "mcpServers": {
    "graphthulhu": {
      "command": "graphthulhu",
      "env": {
        "LOGSEQ_API_URL": "http://127.0.0.1:12315",
        "LOGSEQ_API_TOKEN": "your-token-here"
      }
    }
  }
}

Logseq — Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "graphthulhu": {
      "command": "graphthulhu",
      "env": {
        "LOGSEQ_API_URL": "http://127.0.0.1:12315",
        "LOGSEQ_API_TOKEN": "your-token-here"
      }
    }
  }
}

Obsidian — Claude Code

{
  "mcpServers": {
    "graphthulhu": {
      "command": "graphthulhu",
      "args": ["--backend", "obsidian", "--vault", "/path/to/your/vault"],
      "env": {}
    }
  }
}

Obsidian — Claude Desktop

{
  "mcpServers": {
    "graphthulhu": {
      "command": "graphthulhu",
      "args": ["--backend", "obsidian", "--vault", "/path/to/your/vault"],
      "env": {}
    }
  }
}

Read-only mode

To disable all write operations (Logseq — Obsidian is always read-only):

{
  "mcpServers": {
    "graphthulhu": {
      "command": "graphthulhu",
      "args": ["--read-only"],
      "env": {
        "LOGSEQ_API_URL": "http://127.0.0.1:12315",
        "LOGSEQ_API_TOKEN": "your-token-here"
      }
    }
  }
}

Version control warning

On startup with the Logseq backend, graphthulhu checks if your graph directory is git-controlled. If not, it prints a warning to stderr suggesting you initialize version control. Write operations cannot be undone without it.

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | LOGSEQ_API_URL | http://127.0.0.1:12315 | Logseq HTTP API endpoint | | LOGSEQ_API_TOKEN | (required for Logseq) | Bearer token from Logseq settings | | GRAPHTHULHU_BACKEND | logseq | Backend type: logseq or obsidian | | OBSIDIAN_VAULT_PATH | — | Path to Obsidian vault root |

Architecture

main.go              Entry point — backend routing, MCP server startup
cli.go               CLI subcommands: journal, add, search
server.go            MCP server setup — conditional tool registration
backend/backend.go   Backend interface + optional capability interfaces
client/logseq.go     Logseq HTTP API client with retry/backoff
vault/
  vault.go           Obsidian vault client — reads .md files into Backend interface
  markdown.go        Markdown → block tree parser (heading-based sectioning)
  frontmatter.go     YAML frontmatter parser
  index.go           Backlink index builder from [[wikilinks]]
tools/
  navigate.go        Page, block, links, references, BFS traversal
  search.go          Full-text, property, DataScript/frontmatter, tag search
  analyze.go         Graph overview, connections, gaps, c