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
npm install -g logseq-mcp-server
🚀 Quick Setup (3 Steps)
Step 1: Configure Logseq
- Enable HTTP API: Settings → Features → HTTP APIs server
- Generate API Token: API → Authorization tokens → Add new token
- Start server
Step 2: Choose Your AI Client
📱 Claude Desktop
Method 1: Configuration File (Recommended)
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"logseq": {
"command": "npx",
"args": ["logseq-mcp-server"],
"env": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
After saving: Completely restart Claude Desktop
Method 2: Terminal Command
macOS/Linux:
echo '{"mcpServers":{"logseq":{"command":"npx","args":["logseq-mcp-server"],"env":{"LOGSEQ_API_URL":"http://127.0.0.1:12315","LOGSEQ_API_TOKEN":"your-api-token-here"}}}}' > ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows (PowerShell):
'{"mcpServers":{"logseq":{"command":"npx","args":["logseq-mcp-server"],"env":{"LOGSEQ_API_URL":"http://127.0.0.1:12315","LOGSEQ_API_TOKEN":"your-api-token-here"}}}}' | Out-File -FilePath "$env:APPDATA\Claude\claude_desktop_config.json" -Encoding utf8
🤖 Claude Code
Method 1: Environment Setup
# Set environment variables and run directly
export LOGSEQ_API_URL="http://127.0.0.1:12315"
export LOGSEQ_API_TOKEN="your-api-token-here"
npx logseq-mcp-server
Method 2: Configuration File
Create or edit your Claude Code MCP configuration:
{
"mcpServers": {
"logseq": {
"command": "npx",
"args": ["logseq-mcp-server"],
"env": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
🔷 VS Code
Method 1: Settings UI
- Open VS Code Settings (Ctrl/Cmd + ,)
- Search for "MCP"
- 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
- Name:
Method 2: Settings JSON
macOS: ~/Library/Application Support/Code/User/settings.json
Windows: %APPDATA%\Code\User\settings.json
{
"mcp": {
"servers": {
"logseq": {
"type": "stdio",
"command": "npx",
"args": ["logseq-mcp-server"],
"env": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
}
Method 3: Terminal Command
macOS:
# Add to VS Code settings.json
cat >> ~/Library/Application\ Support/Code/User/settings.json << 'EOF'
{
"mcp": {
"servers": {
"logseq": {
"type": "stdio",
"command": "npx",
"args": ["logseq-mcp-server"],
"env": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
}
EOF
Windows (PowerShell):
# Add to VS Code settings.json
Add-Content -Path "$env:APPDATA\Code\User\settings.json" -Value @'
{
"mcp": {
"servers": {
"logseq": {
"type": "stdio",
"command": "npx",
"args": ["logseq-mcp-server"],
"env": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
}
'@
🖱️ Cursor
Method 1: Configuration File (Recommended)
macOS: ~/.cursor/mcp.json
Windows: %USERPROFILE%\.cursor\mcp.json
{
"mcpServers": {
"logseq": {
"command": "npx",
"args": ["logseq-mcp-server"],
"env": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
Method 2: Terminal Command
macOS/Linux:
mkdir -p ~/.cursor
echo '{"mcpServers":{"logseq":{"command":"npx","args":["logseq-mcp-server"],"env":{"LOGSEQ_API_URL":"http://127.0.0.1:12315","LOGSEQ_API_TOKEN":"your-api-token-here"}}}}' > ~/.cursor/mcp.json
Windows (PowerShell):
New-Item -Path "$env:USERPROFILE\.cursor" -ItemType Directory -Force
'{"mcpServers":{"logseq":{"command":"npx","args":["logseq-mcp-server"],"env":{"LOGSEQ_API_URL":"http://127.0.0.1:12315","LOGSEQ_API_TOKEN":"your-api-token-here"}}}}' | Out-File -FilePath "$env:USERPROFILE\.cursor\mcp.json" -Encoding utf8
🌪️ Windsurf
Method 1: Configuration File
macOS: ~/Library/Application Support/Windsurf/mcp.json
Windows: %APPDATA%\Windsurf\mcp.json
{
"mcpServers": {
"logseq": {
"command": "npx",
"args": ["logseq-mcp-server-server"],
"env": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
Method 2: Terminal Command
macOS:
mkdir -p ~/Library/Application\ Support/Windsurf
echo '{"mcpServers":{"logseq":{"command":"npx","args":["logseq-mcp-server"],"env":{"LOGSEQ_API_URL":"http://127.0.0.1:12315","LOGSEQ_API_TOKEN":"your-api-token-here"}}}}' > ~/Library/Application\ Support/Windsurf/mcp.json
Windows (PowerShell):
New-Item -Path "$env:APPDATA\Windsurf" -ItemType Directory -Force
'{"mcpServers":{"logseq":{"command":"npx","args":["logseq-mcp-server"],"env":{"LOGSEQ_API_URL":"http://127.0.0.1:12315","LOGSEQ_API_TOKEN":"your-api-token-here"}}}}' | Out-File -FilePath "$env:APPDATA\Windsurf\mcp.json" -Encoding utf8
🌐 Continue.dev
Add to your Continue configuration:
{
"mcpServers": {
"logseq": {
"command": "npx",
"args": ["logseq-mcp-server"],
"env": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
🔧 Zed Editor
Add to your Zed settings:
{
"context_servers": {
"logseq": {
"command": {
"path": "npx",
"args": ["logseq-mcp-server-server"]
},
"settings": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
🧠 Cline (VS Code Extension)
Add to your VS Code settings.json (Cline reads the standard MCP servers map):
{
"mcp": {
"servers": {
"logseq": {
"type": "stdio",
"command": "npx",
"args": ["logseq-mcp-server"],
"env": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
}
🔬 MCP Inspector (Debug/Testing)
Run the Inspector and connect to this server locally:
# macOS/Linux
export LOGSEQ_API_URL="http://127.0.0.1:12315"
export LOGSEQ_API_TOKEN="your-api-token-here"
npx @modelcontextprotocol/inspector --command npx --args logseq-mcp-server
# Windows (PowerShell)
$env:LOGSEQ_API_URL = "http://127.0.0.1:12315"
$env:LOGSEQ_API_TOKEN = "your-api-token-here"
npx @modelcontextprotocol/inspector --command npx --args logseq-mcp-server
🚀 Raycast (Status)
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.
🤖 Other MCP Clients
Method 1: Direct Command
For any MCP-compatible client, run directly:
# Set environment variables
export LOGSEQ_API_URL="http://127.0.0.1:12315"
export LOGSEQ_API_TOKEN="your-api-token-here"
# Run the server
logseq-mcp-server
Method 2: Standard MCP Configuration
Most MCP clients support this standard format:
{
"mcpServers": {
"logseq": {
"command": "npx",
"args": ["logseq-mcp-server"],
"env": {
"LOGSEQ_API_URL": "http://127.0.0.1:12315",
"LOGSEQ_API_TOKEN": "your-api-token-here"
}
}
}
}
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: truerequired foroperation: "remove";control.maxOpsenforced 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: truefor safety - Soft Delete: Move to trash instead of permanent removal
- Dependency Tracking: Handle orphaned references and relationships
💡 Example Usage
Basic Operations
"Search for all TODO items created this week"
"Get the complete content of my 'Project Alpha' page with all backlinks"
"Create a new page called 'Meeting Notes 2024-01-15' with today's agenda"
"Apply my 'Daily Review Template' to create a new review for today"
Advanced Workflows
"Find all pages tagged #project that have status=active, then create a summary page linking to all of them"
"Search for templates related to meetings, then use the best one to create notes for tomorrow's team standup"
"Get the graph structure around 'Machine Learning' and create a comprehensive overview page with all related concepts"
Template System
"List all available templates in my knowledge base"
"Apply the 'Project Template' with variables: name='Website Redesign', deadline='March 1st', team='Design'"
"Create a new template called 'Book Notes' for capturing reading highlights"
🎯 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
| Problem | Solution |
|---|---|
| Connection Refused | Ensure Logseq is running with HTTP API enabled |
| Unauthorized | Check your API token and regenerate if needed |
| Slow Performance | Increase timeout settings or check network connectivity |
| Template Errors | Ensure templates are single blocks (Logseq requirement) |
| Server Won't Start | Try npx -y logseq-mcp-server@latest to force fresh install |
| Cache Issues | Use npx --yes logseq-mcp-server@latest to bypass cache |
Getting the Latest Version
If you're experiencing issues, make sure you're running the latest version:
# Force install the latest version (bypasses npm cache)
npx -y logseq-mcp-server@latest
# Alternative syntax
npx --yes logseq-mcp-server@latest
# Check current version
npx logseq-mcp-server --version
Debug Mode
# Enable debug logging
DEBUG=1 logseq-mcp-server
# Set custom log level
LOG_LEVEL=debug logseq-mcp-server
Environment Variables
# Core Configuration (Required)
export LOGSEQ_API_URL="http://127.0.0.1:12315"
export LOGSEQ_API_TOKEN="your-api-token-here"
# Performance Tuning (Optional)
export LOGSEQ_TIMEOUT="30000" # 30 second timeout
export LOGSEQ_MAX_RETRIES="5" # 5 retry attempts
# Logging (Optional)
# Default: 'error' in production or when NODE_ENV is unset; 'info' in development
# Override to increase verbosity when needed:
# export LOG_LEVEL="info" # e.g., operational logs in prod
export NODE_ENV="production" # Environment mode
📚 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:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes with tests
- Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development Setup
# Clone the repository
git clone https://github.com/eugeneyvt/logseq-mcp-server
cd logseq-mcp-server
# Install dependencies
npm install
# Set up environment
cp .env.example .env
# Edit .env with your Logseq configuration
# Start development
npm run dev
# Run tests
npm test
# Build for production
npm run build
🌟 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
