# anshulbansod2/logseq-mcp architecture

> Architecture diagram of the GitHub repository anshulbansod2/logseq-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anshulbansod2/logseq-mcp
- Repository: https://github.com/anshulbansod2/logseq-mcp

## Overview

logseq-mcp is an MCP server that exposes safe, high-level operations on Logseq DB graphs. An AI client invokes registered read or write tools; the graph service applies DB-graph conventions and validation, then uses a single HTTP client to call Logseq’s local API. Reads cover notes, tasks, projects, journals, links, cards, and graph configuration; writes include tasks, notes, projects, queries, links, cards, and guarded soft deletion. The tool-module call links are supported by the SOURCE INDEX; unsampled implementations are represented at module level.

Main entry points: [`src/logseq_mcp/server.py`](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/server.py) (MCP server), [`src/logseq_mcp/graph/writer.py`](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/graph/writer.py) (Graph writer), [`src/logseq_mcp/graph/reader.py`](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/graph/reader.py) (Graph reader), [`src/logseq_mcp/client.py`](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/client.py) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP interface"]
  node_server["MCP server<br/>[server.py]"]
  node_readtools["Read tools<br/>[read.py]"]
  node_tasktools["Task tools<br/>[tasks.py]"]
  node_projecttools["Project tools<br/>[projects.py]"]
  node_notetools["Note tools<br/>[notes.py]"]
  node_linktools["Link tools<br/>[links.py]"]
  node_cardtools["Card tools<br/>[cards.py]"]
  node_querytools["Query tools<br/>[queries.py]"]
  node_admintools["Admin tools<br/>[admin.py]"]
end

subgraph group_domain["Graph workflows"]
end

subgraph group_service["Graph service"]
  node_reader["Graph reader<br/>[reader.py]"]
  node_writer["Graph writer<br/>[writer.py]"]
  node_base["Shared graph primitives<br/>[_base.py]"]
  node_conventions["DB conventions<br/>[conventions.py]"]
  node_models["Tool schemas<br/>[models.py]"]
end

subgraph group_transport["Logseq integration"]
  node_config["Settings<br/>[config.py]"]
  node_client["HTTP client<br/>[client.py]"]
end

node_agent(("AI agent"))
node_logseq["Logseq desktop API"]

node_agent -->|"invokes tools"| node_server
node_server -->|"registers tools"| node_readtools
node_server -->|"registers tools"| node_tasktools
node_server -->|"registers tools"| node_projecttools
node_server -->|"registers tools"| node_notetools
node_server -->|"registers tools"| node_linktools
node_server -->|"registers tools"| node_cardtools
node_server -->|"registers tools"| node_querytools
node_server -->|"registers tools"| node_admintools
node_readtools -->|"calls graph"| node_reader
node_tasktools -->|"calls graph"| node_writer
node_projecttools -->|"calls graph"| node_writer
node_notetools -->|"calls graph"| node_writer
node_linktools -->|"calls graph"| node_writer
node_cardtools -->|"calls graph"| node_writer
node_querytools -->|"calls graph"| node_writer
node_admintools -->|"calls graph"| node_writer
node_server -->|"serves resources"| node_reader
node_reader -->|"inherits primitives"| node_base
node_writer -->|"inherits primitives"| node_base
node_reader -->|"builds queries"| node_conventions
node_writer -->|"applies rules"| node_conventions
node_reader -->|"returns schemas"| node_models
node_writer -->|"returns schemas"| node_models
node_base -->|"sends API calls"| node_client
node_client -->|"uses settings"| node_config
node_client -->|"posts requests"| node_logseq

click node_server "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/server.py"
click node_readtools "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/read.py"
click node_tasktools "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/tasks.py"
click node_projecttools "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/projects.py"
click node_notetools "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/notes.py"
click node_linktools "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/links.py"
click node_cardtools "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/cards.py"
click node_querytools "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/queries.py"
click node_admintools "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/admin.py"
click node_reader "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/graph/reader.py"
click node_writer "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/graph/writer.py"
click node_base "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/graph/_base.py"
click node_conventions "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/conventions.py"
click node_models "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/models.py"
click node_config "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/config.py"
click node_client "https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_readtools,node_tasktools,node_projecttools,node_notetools,node_linktools,node_cardtools,node_querytools,node_admintools toneBlue
class node_reader,node_writer,node_base,node_conventions,node_models,node_logseq toneMint
class node_config,node_client toneRose
class node_agent toneIndigo
```

## Components

### MCP interface

- [MCP server](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/server.py): `src/logseq_mcp/server.py`
- [Read tools](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/read.py): `src/logseq_mcp/tools/read.py`
- [Task tools](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/tasks.py): `src/logseq_mcp/tools/tasks.py`
- [Project tools](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/projects.py): `src/logseq_mcp/tools/projects.py`
- [Note tools](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/notes.py): `src/logseq_mcp/tools/notes.py`
- [Link tools](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/links.py): `src/logseq_mcp/tools/links.py`
- [Card tools](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/cards.py): `src/logseq_mcp/tools/cards.py`
- [Query tools](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/queries.py): `src/logseq_mcp/tools/queries.py`
- [Admin tools](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/tools/admin.py): `src/logseq_mcp/tools/admin.py`

### Graph service

- [Graph reader](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/graph/reader.py): `src/logseq_mcp/graph/reader.py`
- [Graph writer](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/graph/writer.py): `src/logseq_mcp/graph/writer.py`
- [Shared graph primitives](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/graph/_base.py): `src/logseq_mcp/graph/_base.py`
- [DB conventions](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/conventions.py): `src/logseq_mcp/conventions.py`
- [Tool schemas](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/models.py): `src/logseq_mcp/models.py`

### Logseq integration

- [Settings](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/config.py): `src/logseq_mcp/config.py`
- [HTTP client](https://github.com/anshulbansod2/logseq-mcp/blob/main/src/logseq_mcp/client.py): `src/logseq_mcp/client.py`

### Other components

- **AI agent**
- **Logseq desktop API**

## Connections

- AI agent → MCP server: invokes tools (evidence: `README.md`)
- MCP server → Read tools: registers tools (evidence: `src/logseq_mcp/server.py`)
- MCP server → Task tools: registers tools (evidence: `src/logseq_mcp/server.py`)
- MCP server → Project tools: registers tools (evidence: `src/logseq_mcp/server.py`)
- MCP server → Note tools: registers tools (evidence: `src/logseq_mcp/server.py`)
- MCP server → Link tools: registers tools (evidence: `src/logseq_mcp/server.py`)
- MCP server → Card tools: registers tools (evidence: `src/logseq_mcp/server.py`)
- MCP server → Query tools: registers tools (evidence: `src/logseq_mcp/server.py`)
- MCP server → Admin tools: registers tools (evidence: `src/logseq_mcp/server.py`)
- Read tools → Graph reader: calls graph (evidence: `src/logseq_mcp/tools/read.py`)
- Task tools → Graph writer: calls graph (evidence: `src/logseq_mcp/tools/tasks.py`)
- Project tools → Graph writer: calls graph (evidence: `src/logseq_mcp/tools/projects.py`)
- Note tools → Graph writer: calls graph (evidence: `src/logseq_mcp/tools/notes.py`)
- Link tools → Graph writer: calls graph (evidence: `src/logseq_mcp/tools/links.py`)
- Card tools → Graph writer: calls graph (evidence: `src/logseq_mcp/tools/cards.py`)
- Query tools → Graph writer: calls graph (evidence: `src/logseq_mcp/tools/queries.py`)
- Admin tools → Graph writer: calls graph (evidence: `src/logseq_mcp/tools/admin.py`)
- MCP server → Graph reader: serves resources (evidence: `src/logseq_mcp/server.py`)
- Graph reader → Shared graph primitives: inherits primitives (evidence: `src/logseq_mcp/graph/_base.py`)
- Graph writer → Shared graph primitives: inherits primitives (evidence: `src/logseq_mcp/graph/_base.py`)
- Graph reader → DB conventions: builds queries (evidence: `src/logseq_mcp/graph/reader.py`)
- Graph writer → DB conventions: applies rules (evidence: `src/logseq_mcp/graph/writer.py`)
- Graph reader → Tool schemas: returns schemas (evidence: `src/logseq_mcp/graph/reader.py`)
- Graph writer → Tool schemas: returns schemas (evidence: `src/logseq_mcp/graph/writer.py`)
- Shared graph primitives → HTTP client: sends API calls (evidence: `src/logseq_mcp/graph/_base.py`)
- HTTP client → Settings: uses settings (evidence: `src/logseq_mcp/client.py`)
- HTTP client → Logseq desktop API: posts requests (evidence: `src/logseq_mcp/client.py`)
