gustavo-meilus/logseq-api-mcp

Logseq API MCP Server

Model Context Protocol server for Logseq API integration with dynamic tool discovery

Table of Contents

• Overview
• Features
• Installation
• Configuration
• Available Tools
• Tool Details & Examples
• Usage Examples
• Development
• Adding New Tools
• Testing
• CI/CD Pipeline
• Contributing
• License

Overview

The Logseq API MCP Server provides seamless integration between Model Context Protocol clients and Logseq knowledge bases. This server enables AI assistants and other MCP clients to interact with your Logseq notes, extract educational content, analyze knowledge relationships, and work with structured information through a comprehensive set of specialized tools.

🚀 Key Innovation: Features a dynamic tool discovery system that automatically detects, imports, and registers any new tools added to the src/tools/ directory - zero configuration required!

Perfect for:

• 📚 Educational Content Management - Extract and organize flashcards and study materials
• 🎓 Learning Systems - Build AI-powered study assistants and spaced repetition tools
• 🔍 Knowledge Base Analysis - Discover relationships and patterns in your notes
• 📊 Content Discovery - Navigate complex knowledge graphs with AI assistance
• 🧠 Academic Research - Analyze course materials and learning resources

Features

🛠️ Core Tools (9 Available)

Read Operations

1. get_all_pages - Complete page listing with metadata
2. get_page_blocks - Hierarchical block structure analysis
3. get_page_links - Page relationship and reference discovery
4. get_block_content - Detailed block content with children
5. get_all_page_content - Comprehensive page content extraction
6. get_linked_flashcards - Advanced flashcard collection and analysis

Write Operations

7. append_block_in_page - Append blocks to pages with positioning options
8. create_page - Create new pages with properties and format
9. edit_block - Edit existing blocks with content, properties, and cursor control

🔄 Dynamic Tool Discovery

• Auto-Discovery - Automatically finds and imports tools from src/tools/
• Zero Configuration - No manual imports or registrations needed
• Instant Integration - New tools are immediately available
• CI Validation - Automated testing ensures all tools work correctly

🎯 Optimized for AI/LLM Consumption

• Clean Structured Output - Emoji-enhanced, hierarchical formatting
• Educational Content Focus - Specialized flashcard and learning material extraction
• Comprehensive Metadata - Block IDs, UUIDs, timestamps, properties, and relationships
• Smart Content Organization - Automatic categorization and summary generation
• Language Agnostic - Works with any Logseq knowledge base language

Installation

Prerequisites

• Python 3.11+ - Modern Python with async/await support
• uv - Fast Python package manager and project management
• Running Logseq instance with API enabled
• Logseq API token for authentication

Quick Setup

1. Clone the repository

   git clone https://github.com/gustavo-meilus/logseq-api-mcp.git
   cd logseq-api-mcp
   

2. Install with uv

   uv sync
   

3. Configure environment

   cp .env.template .env
   # Edit .env with your Logseq API details
   

4. Start the server

   uv run mcp run src/server.py
   

Configuration

Create a .env file in the project root:

# Logseq API Configuration
LOGSEQ_API_ENDPOINT=http://127.0.0.1:12315/api
LOGSEQ_API_TOKEN=your_api_token_here

Getting Your Logseq API Token

1. Open Logseq application
2. Go to Settings → Features → Developer mode
3. Enable "HTTP APIs server"
4. Copy the displayed API token
5. Note the API endpoint (default: http://127.0.0.1:12315/api)
6. Activate the API

Available Tools

Tool Details & Examples

🗂️ get_all_pages

Purpose: Get a clean listing of all pages in your knowledge base

Output Format:

📊 LOGSEQ PAGES LISTING
📈 Total pages: 568
📅 Journal pages: 135
📄 Regular pages: 433

📄 REGULAR PAGES:
📄 Domain Driven Design (DDD) I | ID: 3460 | UUID: 682cfd19-7df6-46e0-a6f3-c09eca3b2530
📄 MBA Engenharia de Software | ID: 170 | UUID: 682fa28c-a3cc-47f2-ae65-7b7db57e1d67

Use Cases:

• Knowledge base exploration
• Page inventory and organization
• Finding specific pages by name or metadata

🌳 get_page_blocks

Purpose: Get hierarchical block structure of any page

Example Input: "Domain Driven Design (DDD) I"

Output Features:

• Tree structure with indentation levels
• Block IDs, UUIDs, and parent-child relationships
• Property extraction and metadata
• Multi-level hierarchy support (up to 8+ levels)

Sample Output:

🌳 PAGE BLOCKS TREE STRUCTURE
📄 Page: Domain Driven Design (DDD) I (ID: 3460)
📊 Total blocks: 1

📋 tipo:: #aula curso:: [[MBA Engenharia de Software]]
   📊 ID:3544 | UUID:682cfd19-2826-46b7-8222-0821b11abc60 | Level:1
   👇 Children: 7

  H1 # Flashcards [heading: 1]
     📊 ID:3552 | UUID:682cfd19-4c9c-40dd-8cb1-c2625315b8ae | Level:2
     👇 Children: 10

🔗 get_page_links

Purpose: Find all pages that link to a target page

Example Result for "Domain Driven Design (DDD) I":

🔗 PAGE LINKS ANALYSIS
📄 Target Page: Domain Driven Design (DDD) I
📊 Found 1 pages linking to this page

📄 1. Domain Driven Design (DDD) II
   🔑 ID: 3588 | UUID: 682cfd19-3a24-4636-a5d5-c62ea57d352e
   📊 References: 1 | Journal: No
   ⚙️ Properties: relacionado: Domain Driven Design (DDD) I

Applications:

• Discover related content and cross-references
• Build knowledge maps and relationship graphs
• Find course sequences and learning paths

🔍 get_block_content

Purpose: Get detailed information about a specific block and its immediate children

Example Input: UUID 682cfd19-3c3f-427c-a0be-c5a3a197ea20

Output:

🔍 MAIN BLOCK
📌 Block ID: 3465
🔑 UUID: 682cfd19-3c3f-427c-a0be-c5a3a197ea20

📝 CONTENT:
💡 Flashcard
Por que o DDD prioriza a colaboração entre desenvolvedores e especialistas do domínio? #card
+ [ ] Porque os especialistas do domínio são responsáveis apenas por aprovar a infraestrutura tecnológica.
+ [ ] Para garantir que o software seja construído com base no conhecimento profundo do domínio, reduzindo ambiguidades e erros.

👶 IMMEDIATE CHILDREN:
🔸 CHILD 1:
Resposta Correta: Para garantir que o software seja construído com base no conhecimento profundo do domínio, reduzindo ambiguidades e erros.

📖 get_all_page_content

Purpose: Extract comprehensive content from a page including properties, blocks, and linked references

Key Features:

• Complete hierarchical content structure
• Property extraction and formatting
• Flashcard identification and extraction
• Linked references analysis
• Educational content optimization

Example Summary:

📖 Domain Driven Design (DDD) I
📊 1 blocks | 1 linked sources

📄 COMPREHENSIVE CONTENT:
📄 Page Properties [3544]
   📋 curso: MBA Engenharia de Software | tipo: aula | professor: Guilherme Bezerra de Lima

🎯 # Flashcards [3552]
   💡 Flashcard [3465]
      ❓ Q: Por que o DDD prioriza a colaboração entre desenvolvedores e especialistas do domínio?

✏️ append_block_in_page

Purpose: Append new blocks to any page with precise positioning control

Key Features:

• Positioning Options - Insert before specific blocks, as siblings, or at page end
• Page-level Blocks - Support for page-level block creation
• Content Flexibility - Support for any text content including markdown
• Immediate Feedback - Detailed confirmation with positioning information

Example Usage:

# Basic block append
await append_block_in_page("My Page", "New content here")

# Positioned before specific block
await append_block_in_page("My Page", "Important note", before="block-uuid-123")

# As sibling of another block
await append_block_in_page("My Page", "Related content", sibling="block-uuid-456")

# Page-level block
await append_block_in_page("My Page", "Page property", is_page_block=True)

Output Example:

✅ **BLOCK APPENDED SUCCESSFULLY**
📄 Page: My Page
📝 Content: New content here
📍 Positioned: At the end of the page
🔗 **NEXT STEPS:**
• Check your Logseq graph to see the new block
• Use get_page_blocks to verify the block was added
• Use get_block_content to get details of the new block

📄 create_page

Purpose: Create new pages with custom properties and formatting

Key Features:

• Property Support - Add custom properties and metadata
• Format Options - Support for markdown and org formats
• Journal Detection - Automatic journal page recognition
• Comprehensive Metadata - Full page entity information

Example Usage:

# Basic page creation
await create_page("New Page")

# With properties
properties = {"status": "active", "priority": "high"}
await create_page("Project Page", properties=properties)

# With format specification
await create_page("Org Page", format="org")

# Complete page with all options
await create_page("Complete Page", properties=properties, format="markdown")

Output Example:

✅ **PAGE CREATED SUCCESSFULLY**
📄 Page: New Page
⚙️ Properties set: 2 items
📝 Format: markdown
🔗 **NEXT STEPS:**
• Check your Logseq graph to see the new page
• Use get_all_pages to verify the page was created
• Use get_page_blocks to start adding content

✏️ edit_block

Purpose: Edit existing blocks with full control over content, properties, and behavior

Key Features:

• Content Editing - Modify block content with preview
• Property Management - Add, update, or remove block properties
• Cursor Control - Position cursor at specific locations
• Focus Management - Control block focus after editing

Example Usage:

# Edit content only
await edit_block("block-uuid-123", content="Updated content")

# Update properties
properties = {"status": "completed", "priority": "high"}
await edit_block("block-uuid-123", properties=properties)

# Set cursor position and focus
await edit_block("block-uuid-123", cursor_position=10, focus=True)

# Complete edit with all options
await edit_block("block-uuid-123",
                content="New content",
                properties=properties,
                cursor_position=5,
                focus=True)

Output Example:

✅ **BLOCK EDITED SUCCESSFULLY**
🔑 Block UUID: block-uuid-123
📝 **UPDATED CONTENT:**

New content

⚙️ **UPDATED PROPERTIES:**
• status: completed
• priority: high
📍 Cursor positioned at index 5
🎯 Focus: Enabled
🔗 **NEXT STEPS:**
• Check your Logseq graph to see the updated block
• Use get_block_content to verify the changes
• Continue editing or add more content

🧠 get_linked_flashcards

Purpose: Comprehensive flashcard extraction from target page and all linked pages

Real Example Results for "Domain Driven Design (DDD) I":

🎯 LINKED FLASHCARDS ANALYSIS
📄 Target Page: Domain Driven Design (DDD) I
🔗 Searched 2 pages (target + 1 linked)
💡 Found 20 flashcards total

📚 Domain Driven Design (DDD) I (10 flashcards)
📚 Domain Driven Design (DDD) II (10 flashcards)

📊 SUMMARY:
• Total flashcards: 20
• Total answer blocks: 0
• Pages with flashcards: 2
• Average answers per flashcard: 0.0

Advanced Features:

• Multi-choice question support
• Answer block extraction and linking
• Cross-page flashcard discovery
• Educational metadata preservation
• Learning system integration ready

Usage Examples

Add to your Claude Desktop MCP settings (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "logseq-api": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/logseq-api-mcp",
        "python",
        "src/server.py"
      ],
      "env": {
        "LOGSEQ_API_ENDPOINT": "http://127.0.0.1:12315/api",
        "LOGSEQ_API_TOKEN": "your_token_here"
      }
    }
  }
}

Note: Replace /path/to/logseq-api-mcp with the actual path to your cloned repository.

Development

Project Structure

logseq-api-mcp/
├── .github/
│   ├── workflows/             # GitHub Actions CI/CD
│   │   ├── test.yml           # Main test suite
│   │   ├── pr-validation.yml  # PR validation
│   │   ├── comprehensive-test.yml # Extended testing
│   │   └── quality.yml        # Code quality & security
│   ├── ISSUE_TEMPLATE/        # Issue templates
│   └── pull_request_template.md # PR template
├── src/
│   ├── server.py              # MCP server implementation
│   ├── registry.py            # Dynamic tool discovery & registration
│   └── tools/                 # Tool implementations (auto-discovered)
│       ├── __init__.py        # Dynamic tool importer
│       ├── get_all_pages.py   # Page listing tool
│       ├── get_page_blocks.py # Block structure tool
│       ├── get_page_links.py  # Page links tool
│       ├── get_block_content.py # Block detail tool
│       ├── get_all_page_content.py # Complete content tool
│       ├── get_linked_flashcards.py # Flashcard extraction tool
│       ├── append_block_in_page.py # Block creation tool
│       ├── create_page.py     # Page creation tool
│       └── edit_block.py      # Block editing tool
├── tests/
│   ├── conftest.py            # Shared test fixtures
│   ├── test_append_block_in_page.py # Block creation tests
│   ├── test_create_page.py    # Page creation tests
│   ├── test_edit_block.py     # Block editing tests
│   ├── test_get_tools.py      # Read operation tests
│   ├── test_mcp_server.py     # Server validation tests
│   ├── test_runner.py         # Test runner utility
│   └── TEST_SUMMARY.md        # Test documentation
├── pyproject.toml             # UV project configuration
├── .env.template              # Environment template
└── README.md                  # This file

Development Setup

# Install with development dependencies
uv sync --dev

# Format code (auto-fixes issues)
uv run ruff check --fix && uv run ruff format

# Test server with MCP inspector
uv run mcp dev src/server.py

# Run server directly
uv run mcp run src/server.py

Adding New Tools

Thanks to the dynamic discovery system, adding new tools is incredibly simple:

1. Create Your Tool File

Create src/tools/your_new_tool.py:

def your_new_tool(param: str) -> dict:
    """
    Your tool description here.

    Args:
        param: Description of parameter

    Returns:
        Dict with tool results
    """
    return {
        "result": f"Processed: {param}",
        "status": "success"
    }

2. That's It! 🎉

The system automatically:

• ✅ Discovers your tool file
• ✅ Imports the function
• ✅ Registers it with the MCP server
• ✅ Validates it in CI tests

Tool Requirements

• File location: Must be in src/tools/ directory
• Function visibility: Don't start function names with _
• File naming: Don't start filenames with _
• Documentation: Include docstring with description
• Type hints: Use for better IDE support

Dynamic Discovery Process

New Tool File → Auto-Scan → Import → Registration → Validation

1. Auto-Scan: src/tools/__init__.py scans directory for .py files
2. Import: Dynamically imports all public functions
3. Registration: src/registry.py auto-registers with MCP server
4. Validation: Tests automatically verify tool presence

Testing

Automated Testing

The project includes comprehensive automated testing with 68 test cases covering all functionality:

# Run the full test suite
uv run pytest tests/ --cov=src/tools --cov-report=html

# Run specific tool tests
uv run python tests/test_runner.py --tool append_block_in_page
uv run python tests/test_runner.py --tool create_page
uv run python tests/test_runner.py --tool edit_block

# Run server validation
uv run python tests/test_mcp_server.py

Test Coverage:

• ✅ 68 Test Cases - Comprehensive coverage of all 9 tools
• ✅ Server Health - Ensures MCP server starts correctly
• ✅ Tool Discovery - Validates automatic tool detection
• ✅ Dynamic Registration - Confirms all tools are registered
• ✅ Write Operations - Tests for append, create, and edit tools
• ✅ Read Operations - Tests for all get_* tools
• ✅ Error Handling - HTTP errors, network issues, edge cases
• ✅ CI Integration - Runs automatically on all commits
• ✅ Coverage Reporting - 80% minimum coverage requirement

Manual Testing

# Test with MCP Inspector (interactive)
uv run mcp dev src/server.py

# Direct server testing
uv run mcp run src/server.py

Test Output Example

🔍 Testing MCP Server Health and Tools...
🔧 Discovered tools (auto-discovery): ['append_block_in_page', 'create_page', 'edit_block', 'get_all_page_content', 'get_all_pages', 'get_block_content', 'get_linked_flashcards', 'get_page_blocks', 'get_page_links']

🏥 Testing server health...
✅ Server started and responded successfully
✅ Dynamic tool discovery working correctly

🎉 MCP Server test completed successfully!
   📊 Tools auto-discovered: 9
   🏥 Server health: OK
   🔄 Dynamic discovery: OK

CI/CD Pipeline

The project includes a comprehensive CI/CD pipeline with automated testing, code quality checks, and security scanning.

🚀 Automated Workflows

Pull Request Validation

• ✅ Test Coverage - 80% minimum coverage requirement
• ✅ Code Quality - Ruff linting and MyPy type checking
• ✅ Security Scanning - Bandit security analysis
• ✅ Tool Discovery - Automated tool validation
• ✅ MCP Server Testing - Server startup and functionality tests

Main Test Suite

• ✅ Multi-Python Testing - Python 3.11, 3.12, and 3.13
• ✅ Cross-Platform - Ubuntu, Windows, and macOS
• ✅ Performance Testing - Memory usage and test duration
• ✅ Integration Testing - Real MCP server with tools

Code Quality & Security

• ✅ Daily Security Scans - Automated vulnerability detection
• ✅ Dependency Checking - Safety and license validation
• ✅ Code Standards - Automated formatting and linting
• ✅ Secret Detection - Hardcoded credential scanning

📊 Quality Gates

All workflows must pass for:

• ✅ Code to be merged to main
• ✅ Releases to be published
• ✅ PRs to be approved

🔧 Local Testing

Run the same checks locally:

# Install dependencies
uv sync --dev

# Run tests with coverage
uv run pytest tests/ --cov=src/tools --cov-report=html

# Run linting
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Run type checking
uv run mypy src/ --ignore-missing-imports

# Run security scan
uv run bandit -r src/

# Run dependency check
uv run safety check

📈 Coverage Requirements

• Minimum Coverage: 80% for PR validation
• Target Coverage: 85% for comprehensive testing
• Coverage Tools: pytest-cov with HTML and XML reports

🛡️ Security Features

• Bandit - Python security linter
• Safety - Dependency vulnerability scanner
• Secret Detection - Hardcoded credential detection
• License Check - Dependency license validation

Contributing

We follow GitHub Flow for all contributions. See for complete details.

Quick Start

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/add-search-tool
   

3. Create your tool (just add the file - automatic integration!)

   # Create src/tools/search_tool.py with your function
   

4. Format and test

   uv run ruff check --fix && uv run ruff format
   uv run python tests/test_mcp_server.py
   

5. Commit and push

   git commit -m "feat: add search tool for content discovery"
   git push origin feature/add-search-tool
   

6. Open a Pull Request

Development Benefits

• Zero Configuration - No manual imports or registrations
• Instant Feedback - Tools work immediately after creation
• Automated Validation - CI tests verify everything works
• Clean Architecture - Dynamic system keeps code organized
• Comprehensive Testing - 68 test cases with 80% coverage
• Quality Assurance - Automated linting, type checking, and security
• CI/CD Pipeline - Automated testing on every PR and push

Code Quality Standards

• Python 3.11+ with modern async/await patterns
• PEP 8 compliance via Ruff formatting
• Type hints for better IDE support
• Error handling with comprehensive exception management
• Environment variables for configuration
• Modular design with dynamic tool loading

Documentation & Resources

• Model Context Protocol Documentation
• Logseq API Documentation
• MCP Python SDK
• UV Package Manager

License

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

Acknowledgments

• Model Context Protocol for the excellent protocol specification
• Logseq for the powerful knowledge management platform
• MCP Python SDK for the robust development framework
• UV for modern Python package management

Made for the Logseq and MCP communities