Skip to main content
Glama
ruliana

mcp-pkm-logseq

by ruliana
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

mcp-pkm-logseq MCP server

A MCP server for interacting with your Logseq Personal Knowledge Management system using custom instructions

Components

Resources

  • logseq://guide - Initial instructions on how to interact with this knowledge base

Tools

  • get_personal_notes_instructions() - Get instructions on how to use the personal notes tool

  • get_personal_notes(topics, from_date, to_date) - Retrieve personal notes from Logseq that are tagged with the specified topics

  • get_todo_list(done, from_date, to_date) - Retrieve the todo list from Logseq

Related MCP server: Logseq MCP Tools

Configuration

The following environment variables can be configured:

  • LOGSEQ_API_KEY: API key for authenticating with Logseq (default: "this-is-my-logseq-mcp-token")

  • LOGSEQ_URL: URL where the Logseq HTTP API is running (default: "http://localhost:12315")

Quickstart

Install

Claude Desktop and Cursor

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "mcp-pkm-logseq": {
    "command": "uvx",
    "args": [
      "mcp-pkm-logseq"
    ],
    "env": {
      "LOGSEQ_API_TOKEN": "your-logseq-api-token",
      "LOGSEQ_URL": "http://localhost:12315"
    }
  }
}

Claude Code

claude mcp add mcp-pkm-logseq uvx mcp-pkm-logseq

Start Logseq server

Logseq's HTTP API is an interface that runs within your desktop Logseq application. When enabled, it starts a local HTTP server (default port 12315) that allows programmatic access to your Logseq knowledge base. The API supports querying pages and blocks, searching content, and potentially modifying content through authenticated requests.

To enable the Logseq HTTP API server:

  1. Open Logseq and go to Settings (upper right corner)

  2. Navigate to Advanced

  3. Enable "Developer mode"

  4. Enable "HTTP API Server"

  5. Set your API token (this should match the LOGSEQ_API_KEY value in the MCP server configuration)

For more detailed instructions, see: https://logseq-copilot.eindex.me/doc/setup

Create MCP PKM Logseq Page

Create a page named "MCP PKM Logseq" in your Logseq graph to serve as the guide for AI assistants. Add the following content:

  • Description of your tagging system (e.g., which tags represent projects, areas, resources)

  • List of frequently used tags and what topics they cover

  • Common workflows you use to organize information

  • Naming conventions for pages and blocks

  • Instructions on how you prefer information to be retrieved

  • Examples of useful topic combinations for searching

  • Any context about your personal knowledge management approach

This page will be displayed whenever the AI thinks it needs to understand the user.

Development

Building and Publishing

To prepare the package for distribution:

  1. Sync dependencies and update lockfile:

uv sync

  1. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

  1. Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

  • Token: --token or UV_PUBLISH_TOKEN

  • Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /Users/ronie/MCP/mcp-pkm-logseq run mcp-pkm-logseq

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

Add Development Servers Configuration to Claude Desktop

"mcpServers": {
  "mcp-pkm-logseq": {
    "command": "uv",
    "args": [
      "--directory",
      "/<parent-directories>/mcp-pkm-logseq",
      "run",
      "mcp-pkm-logseq"
    ],
    "env": {
      "LOGSEQ_API_TOKEN": "your-logseq-api-token",
      "LOGSEQ_URL": "http://localhost:12315"
    }
  }
}

Available Tools

3 tools
get_personal_notesA

Retrieve personal notes from Logseq.

Use this to find relavant information about a specific topic or about user preferences.
It will return all information that is tagged with the topics from the user's personal
knowledge base.

The information is returned in markdown format, each item in the list is a separate
unit of information. Hierachical information is returned as a nested list.

The returning markdown contains text in double square brackets, like this:
`[[topic]]`. These are links to other topics, you can follow them to get more
information. Try variations of the topic to find the most relevant information.

Dates are expressed as:
1. today|yesterday|tomorrow|now
2. <number><unit> like 1d, 2w, 3m, 4y, 2h, 30min

Args:
    topics: A list of topics to search for. Topics are case-insensitive. Topics
            are optional if there is a date range.
    from_date (optional): The start date to filter the notes.
    to_date (optional): The end date to filter the notes.

Returns:
    A markdown formatted string containing the information with the given topics.
    Empty if no information is found.
ParametersJSON Schema
NameRequiredDescriptionDefault
topicsYes
from_dateNo
to_dateNo

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses return format (markdown, nested lists, double-square-bracket links), date format, and empty returns. It lacks details on permissions or rate limits but adequately covers behavioral aspects for a read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with paragraphs and an Args section, but the inclusion of markdown link and date format details, while useful, makes it slightly verbose. Overall, it earns its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description fully explains the return format (markdown, nested list, links) and empty results. All three parameters are documented, and sibling tools are distinguished. It provides sufficient context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning beyond the schema by explaining that topics are case-insensitive and optional with date ranges, and provides date format examples. This compensates for the schema's minimal descriptions, though it could include more on parameter constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Retrieve personal notes from Logseq' and distinguishes from siblings like get_todo_list and get_personal_notes_instructions by focusing on topic-based retrieval of notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies use for finding relevant information on a topic or user preferences and notes that topics are optional if a date range is given. It does not explicitly exclude use cases but provides clear context for when to employ the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_personal_notes_instructionsA

Get instructions on how to use the get_personal_notes tool.

This will return instructions on how the user organizes their personal notes in Logseq.

It will contain common tags (topics), what they mean, and the workflows the user
uses to organize their notes.
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It indicates a read operation returning instructions and organizational details, but does not specify output format (e.g., plain text), response size, or any side effects. More detail would improve transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the core purpose, and every sentence adds meaningful context. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple instruction tool with no parameters and no output schema, the description fully covers what it does and what it returns. It is complete given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters (0 params, 100% schema coverage). The description adds valuable meaning by explaining what the tool returns (instructions, tags, workflows), exceeding the baseline for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns instructions on using the get_personal_notes tool, specifically the user's organization in Logseq including tags and workflows. It distinguishes from siblings like get_personal_notes (retrieves notes) and get_todo_list (retrieves todos).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing guidance on querying personal notes, but does not explicitly state when not to use or mention alternatives beyond naming siblings. The context is clear but lacks exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_todo_listA

Retrieve the todo list from Logseq.

Use this to get a list of all the todos in the user's personal knowledge base.

Dates are expressed as:
1. today|yesterday|tomorrow|now
2. <number><unit> like 1d, 2w, 3m, 4y, 2h, 30min

Args:
    done: Whether to get the done todos or the todo todos.
    from_date (optional): The start date to filter the todos.
    to_date (optional): The end date to filter the todos.

Returns:
    A markdown formatted string containing the todos.
ParametersJSON Schema
NameRequiredDescriptionDefault
doneNo
from_dateNo
to_dateNo

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations present, so description carries full burden. It mentions return format (markdown) and date formats but lacks details on performance, auth, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is structured with Args and Returns sections but could be more concise; date format explanation could be integrated into parameter descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 params, no output schema, and no annotations, description covers purpose, parameters, date format, and return type adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description adds significant meaning: clarifies 'done' param, optional date filters, and date format conventions beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool retrieves todo list from Logseq and distinguishes from siblings (get_personal_notes) by focusing on todos rather than notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage (get todos in personal knowledge base) but does not provide explicit when to use vs alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a distinct purpose: retrieving notes, retrieving instructions for notes retrieval, and retrieving todos. No overlap or ambiguity between them.

Naming Consistency5/5

All tools follow the consistent 'get_' prefix and a descriptive noun pattern (get_personal_notes, get_personal_notes_instructions, get_todo_list). No naming style mixing.

Tool Count4/5

With only 3 tools, the server is minimal but appropriate for a read-only retrieval interface over a personal knowledge base. Slightly scoped down but not underdeveloped for its purpose.

Completeness3/5

Covers retrieval of notes and todos, but lacks any creation, update, or deletion capabilities. While the server may be intentionally read-only, obvious lifecycle operations are missing, limiting agent workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ruliana/mcp-pkm-logseq'

If you have feedback or need assistance with the MCP directory API, please join our Discord server