Logseq MCP Agent

A powerful AI assistant that connects Logseq with Claude and other LLMs using the Model Context Protocol (MCP).

What is it?

Logseq MCP Agent lets AI assistants like Claude directly interact with your Logseq knowledge graph - search your notes, create content, organize information, and manage tasks.

MCP (Model Context Protocol) works like a "USB-C port for AI" - providing a standardized way for AI models to connect with your applications and data. This agent implements MCP to give Claude and other LLMs a direct, structured interface to your Logseq knowledge base.

Think of it as giving Claude direct access to your second brain.

Key Features

📝 Knowledge Management

• Search your entire graph for information
• Generate summaries of pages and content
• Create daily notes with custom sections
• Organize flat pages into nested structures

✅ Task Management

• Find all tasks with specific statuses (TODO, DOING, etc.)
• Extract tasks from meeting notes
• Create and organize task lists
• Track task progress

🔍 Search & Query

• Natural language search across your graph
• Find blocks by content
• Run advanced Datalog queries

📊 Content Organization

• Restructure content hierarchically
• Organize blocks by any criteria
• Transform flat content into nested structures

Quick Setup

Prerequisites

• Logseq with HTTP API enabled
• A Logseq API token
• Claude Desktop or other MCP-compatible AI assistant

Enabling Logseq HTTP API

1. In Logseq → Settings → Advanced: Enable "Developer mode"
2. Restart Logseq
3. In Settings: Enable "HTTP API server"
4. Copy your API token

Setup with Claude Desktop

1. Open Claude Desktop settings
2. Navigate to MCP Servers
3. Add a new server:

   {
     "mcpServers": {
       "logseq": {
         "command": "npx",
         "args": [
           "logseq-mcp"
         ],
         "env": {
           "LOGSEQ_TOKEN": "your_logseq_token"
         }
       }
     }
   }

4. Replace your_logseq_token with your actual token
5. Save and restart Claude

Using Claude with Logseq

Try asking:

• "Find all my TODO tasks in Logseq"
• "Create a daily note with sections for Tasks, Notes, and Journal"
• "Summarize my 'Research' page"
• "Search my notes for information about machine learning"

Alternative Installation

Install via npm:

npx logseq-mcp

Or install globally:

npm install -g logseq-mcp

Configure with a .env file:

LOGSEQ_PORT=12315
LOGSEQ_HOST=127.0.0.1
LOGSEQ_TOKEN=your_logseq_token

Run with:

logseq-mcp

Troubleshooting

• Ensure Logseq is running before starting the agent
• Verify your API token is correct
• Check that the Logseq HTTP API is enabled
• Try debug mode: DEBUG=true logseq-mcp

Debugging

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

You can launch the MCP Inspector via npm with:

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-logseq run mcp-logseq

Technical Details

Built using the Model Context Protocol (MCP), an open standard for connecting AI models with external tools and data sources. The agent acts as an MCP server that provides structured access to your Logseq graph via the Logseq HTTP API.

Development

Setup Development Environment

1. Clone the repository:

   git clone https://github.com/briansunter/logseq-mcp.git
   cd logseq-mcp

2. Install dependencies:

   # Using npm
   npm install
      
   # Using Bun (recommended)
   bun install

Running Tests

The project includes unit and end-to-end tests:

# Run all tests
bun test tests/

# Run unit tests only
bun test:unit

# Run e2e tests only
bun test:e2e

# Run tests in watch mode
bun test:watch

Building

# Standard build
bun run build

# Build for Node.js
bun run build:node

# Build for Bun
bun run build:bun

# Build binaries for various platforms
bun run build:binary           # Current platform
bun run build:macos-arm        # macOS ARM
bun run build:macos-intel      # macOS Intel
bun run build:linux-x64        # Linux x64
bun run build:linux-arm64      # Linux ARM64
bun run build:windows          # Windows
bun run build:all-binaries     # All platforms

Contributing Guidelines

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Commit your changes: git commit -m 'Add some feature'
4. Push to the branch: git push origin feature/your-feature-name
5. Submit a pull request

Please make sure your code passes all tests and follows the existing code style. Add tests for new features.

Contributing & License

Contributions welcome! MIT License.

Contributing

Semantic Versioning

This project uses semantic-release to automatically manage version numbers and create GitHub releases. Version numbers are determined by PR titles using the following conventions:

| PR Title Format | Example | Result | |-----------------|---------|--------| | feat: ... | feat: add new search feature | Minor version increase (0.X.0) | | fix: ... | fix: resolve search bug | Patch version increase (0.0.X) | | feat(breaking): ... | feat(breaking): change API format | Major version increase (X.0.0) |

Other valid prefixes: docs:, style:, refactor:, perf:, test:, chore:, ci:, build: (all result in patch versions).

When merging PRs to master, please follow these conventions in your PR titles to ensure proper versioning.