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

$3

- Node.js >= v18.0.0
- Logseq with HTTP API enabled
- MCP-compatible AI client (Claude Desktop, VS Code, Cursor, etc.)

$3

``bash
npm install -g logseq-mcp-server
`

🚀 Quick Setup (3 Steps)

$3

1. Enable HTTP API: Settings → Features → HTTP APIs server
2. Generate API Token: API → Authorization tokens → Add new token
3. Start server

$3

📱 Claude Desktop

#### Method 1: Configuration File (Recommended)

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

`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:

`bash
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):

`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

`bash


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:

`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"
}
}
}
}
`

🔷 VS Code

#### 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

`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:

`bash


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):

`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

`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:

`bash
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):

`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

`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:

`bash
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):

`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:

`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"
}
}
}
}
`

🔧 Zed Editor

Add to your Zed settings:

`json
{
"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):

`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"
}
}
}
}
}
`

🔬 MCP Inspector (Debug/Testing)

Run the Inspector and connect to this server locally:

`bash


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
`

`powershell


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:

`bash


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:

`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"
}
}
}
}
`

$3

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:

$3

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

$3

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

$3

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.

$3

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

$3

`
"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"
`

$3

`
"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"
`

$3

`
"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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

| 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) |

$3

`bash


Enable debug logging

DEBUG=1 logseq-mcp-server

Set custom log level

LOG_LEVEL=debug logseq-mcp-server
`

$3

`bash


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:

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

$3

`bash


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

---