Logseq MCP - AI-Powered Knowledge Base Integration

Model Context Protocol (MCP) server that enables AI assistants to seamlessly interact with your Logseq knowledge base. Transform your personal notes into an AI-powered workspace with advanced search, content creation, and knowledge management capabilities.

✨ Features

• 🚀 Instant AI Integration - Connect any MCP-compatible AI to your Logseq graph

• 🔒 Privacy First - All operations are local-only, no data leaves your machine

• 🎯 4 Intuitive Tools - Unified Search/Get/Edit/Delete architecture for maximum clarity

• 🔍 Advanced Search - Multi-modal discovery with templates, properties, relations, and date filters

• 🎨 Template System - Single-block template enforcement with proper variable substitution

• ⚡ Enterprise Features - Built with caching, monitoring, security, and idempotency controls

• 🌟 Universal Compatibility - Works with Claude, ChatGPT, and other AI assistants

🛠️ Installation

Requirements

• Node.js >= v18.0.0

• Logseq with HTTP API enabled

• MCP-compatible AI client (Claude Desktop, VS Code, Cursor, etc.)

One-Command Install

🚀 Quick Setup (3 Steps)

Step 1: Configure Logseq

1. Enable HTTP API: Settings → Features → HTTP APIs server

2. Generate API Token: API → Authorization tokens → Add new token

3. Start server

Step 2: Choose Your AI Client

Method 1: Configuration File (Recommended)

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

After saving: Completely restart Claude Desktop

Method 2: Terminal Command

macOS/Linux:

Windows (PowerShell):

Method 1: Environment Setup

Method 2: Configuration File

Create or edit your Claude Code MCP configuration:

Method 1: Settings UI

1. Open VS Code Settings (Ctrl/Cmd + ,)

2. Search for "MCP"

3. Add new server with these settings:

   • Name: logseq

   • Command: npx

   • Args: ["logseq-mcp-server-server"]

   • Environment: LOGSEQ_API_URL=http://127.0.0.1:12315, LOGSEQ_API_TOKEN=your-api-token-here

Method 2: Settings JSON

macOS: ~/Library/Application Support/Code/User/settings.json
Windows: %APPDATA%\Code\User\settings.json

Method 3: Terminal Command

macOS:

Windows (PowerShell):

Method 1: Configuration File (Recommended)

macOS: ~/.cursor/mcp.json
Windows: %USERPROFILE%\.cursor\mcp.json

Method 2: Terminal Command

macOS/Linux:

Windows (PowerShell):

Method 1: Configuration File

macOS: ~/Library/Application Support/Windsurf/mcp.json
Windows: %APPDATA%\Windsurf\mcp.json

Method 2: Terminal Command

macOS:

Windows (PowerShell):

Add to your Continue configuration:

Add to your Zed settings:

Add to your VS Code settings.json (Cline reads the standard MCP servers map):

Run the Inspector and connect to this server locally:

Raycast AI has been rolling out MCP support. If your build exposes MCP server configuration, you can add this server similarly to the examples above (command npx, args ["logseq-mcp-server"], and the two environment variables). If you don’t see MCP settings, this may not be available in your version yet.

Method 1: Direct Command

For any MCP-compatible client, run directly:

Method 2: Standard MCP Configuration

Most MCP clients support this standard format:

Step 3: Start Using

That's it! Your AI assistant now has access to your Logseq knowledge base through 4 powerful tools.

🔧 Available Tools

Logseq MCP provides 4 unified tools that handle all your knowledge base operations:

🔍 search - Advanced Multi-Modal Discovery

Find content across your entire graph with sophisticated filtering:

• Template Discovery: templates:* to list all templates

• Property Search: property:status=open AND date:last-week

• Relationship Analysis: backlinks:"Important Topic"

• Date-Based Queries: date:today, date:last-month

• Combined Filters: Complex AND/OR/NOT queries

📖 get - Unified Content Retrieval

Retrieve detailed information with full context:

• Pages: Complete content with backlinks and graph metrics

• Blocks: Hierarchical content with parent-child relationships

• Templates: Template definitions with variable analysis

• Properties: Page/block metadata and property schemas

• Relations: Graph connections and relationship analysis

• System: Health status and graph statistics

✏️ edit - Comprehensive Content Management

Create, modify, and organize your knowledge:

• Pages: Create, update, append, prepend content

• Blocks: Positional operations with precise placement

• Templates: Single-block enforcement with variable substitution

• Properties: Metadata management and validation

• Relations: Bi-directional link creation and updates

• Safety: Dry-run mode, validation, and rollback support; confirmDestroy: true required for operation: "remove"; control.maxOps enforced to prevent large accidental edits

Notes:

• Properties: When targeting a page, the operation resolves to the page’s root block UUID. The page must already exist (no implicit creation).

• Templates: Creation enforces the Logseq single-block template standard (single root block with content inserted as children when needed). Template insertion is append-only and requires an existing target page.

🗑️ delete - Safe Content Removal

Remove content with comprehensive safety controls:

• Impact Analysis: Preview what will be affected before deletion

• Confirmation Required: Explicit confirmDestroy: true for safety

• Soft Delete: Move to trash instead of permanent removal

• Dependency Tracking: Handle orphaned references and relationships

💡 Example Usage

Basic Operations

Advanced Workflows

Template System

🎯 Key Features

Revolutionary 4-Tool Architecture

• Simplified AI Selection: Instead of 15+ confusing micro-tools, choose from 4 clear action verbs

• Consistent Interface: All tools follow the same parameter patterns and response formats

• Type Safety: Comprehensive validation with helpful error messages

• Production Ready: Built with monitoring, caching, and reliability features

Advanced Search Capabilities

• Multi-Modal Discovery: Search across pages, blocks, templates, tasks simultaneously

• Sophisticated Filtering: Date ranges, properties, tags, relationships, content length

• Cursor-Based Pagination: Handle large result sets efficiently (up to 100 items per page)

• Query Intelligence: Automatic query type detection and optimization

Template System Excellence

• Single-Block Enforcement: Templates must be single blocks (Logseq standard compliance)

• Variable Substitution: Full {{variableName}} placeholder support with validation

• Template Discovery: Easy finding and application of existing templates

• Creation Validation: Automatic format checking and error prevention

Enterprise-Grade Safety

• Idempotency Controls: Prevent duplicate operations with safe retry mechanisms

• Dry-Run Mode: Preview all operations before execution

• Confirmation Prompts: Required confirmation for destructive operations

• Impact Analysis: Comprehensive dependency tracking and orphan detection

• Soft Delete: Recovery options for accidental deletions

📊 Performance Features

Intelligent Caching System

• Page Content: 5-minute TTL with smart invalidation

• Graph Structure: 3-minute TTL with relationship tracking

• Search Results: Optimized caching for repeated queries

• Template Library: Persistent caching for faster template discovery

Connection Management

• HTTP Connection Pooling: Efficient request handling

• Automatic Retry Logic: Exponential backoff for reliability

• Request Deduplication: Prevent duplicate concurrent operations

• Timeout Management: Configurable timeouts for different operation types

Monitoring & Observability

• Real-time Metrics: Operation timing, cache hit rates, error tracking

• Structured Logging: Production-ready logs with sensitive data redaction

• Health Monitoring: Automatic system status checks

• Rate Limiting: Protection against abuse with configurable limits

🔒 Security & Privacy

Privacy-First Design

• Local-Only Operations: No data transmission to external servers

• API Token Security: Tokens never logged or exposed

• Input Sanitization: Comprehensive validation of all user inputs

• Error Sanitization: Sensitive information stripped from error messages

Built-in Protections

• Rate Limiting: Configurable protection against abuse

• Content Validation: Automatic detection and prevention of malicious content

• Secure Defaults: Conservative security settings out of the box

• GDPR Compliance: No data collection or external transmission

🐛 Troubleshooting

Common Issues

Getting the Latest Version

If you're experiencing issues, make sure you're running the latest version:

Debug Mode

Environment Variables

📚 Documentation

• API Reference - Complete tool documentation with examples

• Configuration Guide - Detailed setup and customization options

• Changelog - Version history and release notes

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Make your changes with tests

4. Commit your changes (git commit -m 'Add amazing feature')

5. Push to the branch (git push origin feature/amazing-feature)

6. Open a Pull Request

Development Setup

🌟 Community

• GitHub Issues: Report bugs and request features

• GitHub Discussions: Ask questions and share ideas

• Documentation: Comprehensive guides and examples

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with the Model Context Protocol SDK

• Powered by Logseq's HTTP API

• Inspired by the growing ecosystem of AI-powered knowledge management tools

• Special thanks to the Logseq community for their continuous feedback and support

Transform your Logseq knowledge base into an AI-powered workspace