Connecting to Logseq

When to Use This Skill

This skill auto-invokes when:

• User wants to connect Claude to their Logseq graph

• Setting up Logseq integration or API tokens

• Troubleshooting connection issues

• Configuring graph paths or backends

• User mentions "connect to logseq", "logseq api", "logseq token"

• Questions about HTTP API, CLI, or MCP server setup

Setup Scripts: See {baseDir}/scripts/ for initialization utilities.

Available Backends

Backend Requires Logseq Running Read Write Best For

HTTP API Yes Full Full Real-time, interactive

CLI No Full Limited Offline, batch, CI/CD

MCP Server Yes (via HTTP) Full Full Claude-native tools

Quick Start

1. Enable Logseq HTTP API

In Logseq:

• Settings → Advanced → Developer mode: ON

• Settings → Advanced → HTTP APIs server: ON

• Settings → Advanced → Authorization tokens → Create token

2. Set Environment Variable

export LOGSEQ_API_TOKEN="your-token-here"

3. Initialize Plugin

Run the setup wizard:

python {baseDir}/scripts/init-environment.py

Or use the command: /logseq:init

Backend Details

HTTP API (Primary)

URL: http://127.0.0.1:12315/api

Request Format:

POST /api Content-Type: application/json Authorization: Bearer YOUR_TOKEN

{ "method": "logseq.Editor.getPage", "args": ["PageName"] }

Common Methods:

• logseq.App.getCurrentGraph

• Get current graph info

• logseq.Editor.getPage

• Get page by name

• logseq.Editor.getBlock

• Get block by UUID

• logseq.DB.datascriptQuery

• Execute Datalog query

• logseq.Editor.insertBlock

• Create new block

CLI (@logseq/cli)

Installation:

npm install -g @logseq/cli

Usage:

Query local graph

logseq query "[:find ?title :where [?p :block/title ?title]]" --graph ~/logseq/my-graph

With running Logseq (in-app mode)

logseq query "..." --in-app -a YOUR_TOKEN

MCP Server

The plugin includes a custom MCP server that exposes Logseq operations as Claude tools.

Location: servers/logseq-mcp/

Build:

cd servers/logseq-mcp npm install npm run build

Configuration File

Location: .claude/logseq-expert/env.json

{ "backend": "auto", "http": { "url": "http://127.0.0.1:12315", "token": "${LOGSEQ_API_TOKEN}" }, "cli": { "graphPath": "/path/to/graph", "inApp": false }, "mcp": { "enabled": true }, "preferences": { "defaultGraph": null, "confirmWrites": false, "backupBeforeWrite": false } }

Troubleshooting

"Cannot connect to Logseq"

• Check Logseq is running with HTTP API enabled

• Verify port: Default is 12315, check Settings → Advanced

• Check firewall: Ensure localhost:12315 is accessible

• Test manually: curl -X POST http://127.0.0.1:12315/api
  -H "Content-Type: application/json"
  -H "Authorization: Bearer YOUR_TOKEN"
  -d '{"method":"logseq.App.getCurrentGraph"}'

"Authentication failed"

• Verify token: Check it matches what's in Logseq settings

• Token format: Ensure no extra whitespace

• Environment variable: Check echo $LOGSEQ_API_TOKEN

"CLI not found"

• Install globally: npm install -g @logseq/cli

• Or use npx: npx @logseq/cli --help

• Check PATH: Ensure npm global bin is in PATH

"MCP server not working"

• Build server: cd servers/logseq-mcp && npm run build

• Check Node.js: Requires Node 18+

• Verify HTTP API: MCP server uses HTTP API internally

Scripts Reference

Script Purpose

init-environment.py

Interactive setup wizard

detect-backend.py

Auto-detect available backends

test-connection.py

Test connectivity

preflight-checks.sh

Validate environment

Run scripts from plugin root:

python logseq-expert/scripts/init-environment.py

Security Notes

• Never commit tokens to version control

• Use environment variables for sensitive data

• Token in config supports ${VAR} syntax for env vars

• HTTP API only listens on localhost by default