MCP HubMCP Hub
joelhooks

logseq-mcp-tools

by: joelhooks

mcp server for logseq graph

16created 12/03/2025
Visit
logseq
plugin

📌Overview

Purpose: To enable AI assistants to interact with the Logseq knowledge graph through a structured Model Context Protocol (MCP) server.

Overview: The Logseq MCP Tools project offers a robust server allowing AI assistants, such as Claude, to retrieve and manage data from a Logseq knowledge base effectively. It enhances user interaction with their stored knowledge by providing easy access to important functionalities.

Key Features:

  • getAllPages: Retrieves a comprehensive list of all pages within the Logseq graph, aiding in navigation and organization.

  • getJournalSummary: Generates summaries of journal entries over flexible date ranges, helping users quickly extract insights from their reflections.

  • createPage: Facilitates the creation of new pages in the Logseq graph, enabling users to expand their knowledge base seamlessly.

  • analyzeGraph: Offers a detailed analysis of the knowledge graph, identifying connections, recent updates, and suggesting improvements, which strengthens knowledge synthesis.

This framework enables users to leverage the capabilities of AI while enriching their Logseq experience with powerful tools for knowledge management.

Logseq MCP Tools

A Model Context Protocol (MCP) server that provides AI assistants with structured access to your Logseq knowledge graph.

Overview

This project creates an MCP server that allows AI assistants like Claude to interact with your Logseq knowledge base. It provides tools for:

  • Retrieving a list of all pages
  • Getting content from specific pages
  • Generating journal summaries for flexible date ranges
  • Extracting linked pages and exploring connections

Installation

  1. Clone this repository
  2. Install dependencies using npm, yarn, or pnpm:
# Using npm
npm install

# Using yarn
yarn install

# Using pnpm
pnpm install
  1. Copy the environment template and configure your Logseq token:
cp .env.template .env
# Edit .env with your Logseq authentication token

Configuration

This project includes a .env.template file that you can copy and rename to .env.

To find your Logseq authentication token:

  1. Open Logseq
  2. Enable the HTTP API in Settings > Features > Enable HTTP API
  3. Set your authentication token in Settings > Features > HTTP API Authentication Token

Usage

Running the MCP Server

Start the server using:

# Using the npm script
npm start

# Or directly with tsx
npx tsx index.ts

Connecting with Claude

Claude Desktop

Follow the Claude MCP Quickstart guide:

  1. Install Node.js globally (e.g., via Homebrew):
brew install node
  1. Install the Claude desktop app
  2. Open the Claude menu and select "Settings..."
  3. Click on "Developer" in the left sidebar, then "Edit Config"
  4. Replace the contents of claude_desktop_config.json with:
{
	"mcpServers": {
		"logseq": {
			"command": "npx",
			"args": ["tsx", "/path/to/your/index.ts"]
		}
	}
}

Important: Replace /path/to/your/index.ts with the absolute path to your index.ts file (e.g., /Users/username/Code/logseq-mcp-tools/index.ts).

  1. Save the file and restart Claude Desktop.

You can now ask Claude to use your Logseq data, for example:

  • "Show me my recent journal entries"
  • "Summarize my notes from last week"
  • "Find all pages related to [topic]"

Claude in Cursor

  1. Open Cursor
  2. Add a new MCP service from settings
  3. Enter the command:
npx tsx "/path/to/index.ts"
  1. Give your service a name like "Logseq Tools"

Now you can use Claude in Cursor with your Logseq data.

Claude in Anthropic API (generic)

Add the MCP service with:

claude mcp add "logseq" npx tsx "/path/to/index.ts"

Available Tools

getAllPages

Retrieves a list of all pages in your Logseq graph.

getPage

Gets the content of a specific page.

Parameters:

  • pageName: The name of the page to retrieve

getJournalSummary

Generates a summary of journal entries for a specified date range.

Parameters:

  • dateRange: Natural language date range like "today", "this week", "last month", etc.

Features:

  • Collect journal entries in the specified range
  • Format them readably
  • Extract and analyze referenced pages/concepts
  • Show frequently referenced concepts

createPage

Creates a new page in your Logseq graph.

Parameters:

  • pageName: Name for the new page
  • content: (Optional) Initial content for the page

searchPages

Searches pages by name.

Parameters:

  • query: Search query string

getBacklinks

Finds all pages referencing a specific page.

Parameters:

  • pageName: The page name to find backlinks for

analyzeGraph

Performs a comprehensive analysis of your knowledge graph.

Parameters:

  • daysThreshold: (Optional) Days to look back for recent content (default: 30)

Features:

  • Identifies frequently referenced pages
  • Tracks recent updates
  • Discovers page clusters and connections
  • Lists outstanding tasks
  • Suggests potential updates needed

findKnowledgeGaps

Analyzes your graph to identify gaps and areas for improvement.

Parameters:

  • minReferenceCount: (Optional) Minimum references to consider (default: 3)
  • includeOrphans: (Optional) Include orphaned pages (default: true)

Features:

  • Identifies missing but frequently referenced pages
  • Finds underdeveloped pages
  • Lists orphaned pages with no incoming links
  • Provides summary statistics

analyzeJournalPatterns

Analyzes journal entry patterns over time.

Parameters:

  • timeframe: (Optional) Time period to analyze (e.g., "last 30 days")
  • includeMood: (Optional) Include mood analysis (default: true)
  • includeTopics: (Optional) Include topic analysis (default: true)

Features:

  • Topic trends and evolution
  • Mood pattern analysis
  • Habit tracking statistics
  • Project progress tracking

smartQuery

Executes natural language queries using Logseq's DataScript.

Parameters:

  • request: Natural language query
  • includeQuery: (Optional) Include generated Datalog query
  • advanced: (Optional) Use advanced analysis features

Features:

  • Page connections and relationships
  • Content clustering
  • Task progress analysis
  • Concept evolution tracking

suggestConnections

Uses AI to suggest interesting connections in your graph.

Parameters:

  • minConfidence: (Optional) Minimum confidence (0-1, default: 0.6)
  • maxSuggestions: (Optional) Maximum suggestions (default: 10)
  • focusArea: (Optional) Topic or area to focus on

Features:

  • Discovers potential connections between pages
  • Identifies knowledge synthesis opportunities
  • Suggests exploration paths based on recent interests
  • Provides confidence scores

Development

The server utilizes:

  • Model Context Protocol TypeScript SDK
  • Zod for parameter validation
  • Logseq HTTP API for data access

To add new tools, define additional server.tool() entries in index.ts.

Troubleshooting

Node.js Version Managers (fnm, nvm, etc.)

Claude Desktop cannot access Node.js binaries managed by version managers because it runs outside the shell environment.

Solution: Install system-wide Node.js (e.g., via Homebrew):

brew install node

This ensures Node.js is accessible to all applications, including Claude Desktop.

Basic Troubleshooting Steps

  • Ensure Logseq is running with HTTP API enabled
  • Verify your auth token in .env matches Logseq's
  • Check the index.ts path in the Claude config is correct
  • Run npx tsx index.ts in your terminal to confirm it works

Viewing Logs in Claude Desktop

Monitor logs in real-time on macOS:

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

For detailed debugging, refer to the official MCP debugging documentation at:
https://modelcontextprotocol.io/docs/tools/debugging