mcp-python-logseq

MCP Logseq Knowledge Base

A Model Context Protocol (MCP) server that enables AI assistants to interact with Logseq knowledge base files. This server provides tools for searching notes, reading pages, querying by tags, and consolidating project information.

Features

• Full-text search across all Logseq pages with context-aware results
• Page retrieval by name to read complete note contents
• Tag-based queries to find pages by hashtags
• Journal navigation with date range filtering
• Project consolidation to aggregate all notes tagged with a project tag
• Smart caching with incremental index updates for optimal performance
• Incremental indexing that only re-reads changed files

Available Tools

Tool	Description
search_notes(query)	Full-text search across all Logseq pages
get_page(page_name)	Read a specific Logseq page by name
list_pages(folder)	List all pages in a folder (pages, journals, or all)
get_pages_by_tag(tag)	Find all pages containing a specific #tag
get_journal_range(start_date, end_date)	Read journal entries between dates (YYYY-MM-DD)
consolidate_project(project_tag)	Aggregate all notes tagged with a project tag
get_all_tags()	Get a list of all tags used in the knowledge base
refresh_index()	Force a full re-scan of the Logseq graph

Installation

Prerequisites

• Python 3.10 or higher
• Poetry for dependency management
• A Logseq graph directory

Setup

1. Clone the repository:

   git clone <repository-url>
   cd mcp-python-logseq
   

2. Install dependencies with Poetry:

   poetry install
   

Configure with Claude Code

Add this MCP server to Claude Code using one of these methods:

Method 1: Using claude mcp add

claude mcp add logseq \
  -e LOGSEQ_DIR="~/logseq-graph" \
  -e CACHE_TTL=300 \
  -- poetry run python /path/to/mcp-python-logseq/server.py

Method 2: Using fastmcp install

poetry run fastmcp install claude-code server.py \
  --server-name "logseq" \
  --env LOGSEQ_DIR=~/logseq-graph \
  --env CACHE_TTL=300

Configure with Other MCP Clients

Add the following to your MCP client configuration:

{
  "mcpServers": {
    "logseq": {
      "command": "poetry",
      "args": [
        "run",
        "python",
        "/path/to/mcp-python-logseq/server.py"
      ],
      "env": {
        "LOGSEQ_DIR": "~/logseq-graph",
        "CACHE_TTL": "300"
      }
    }
  }
}

Environment Variables

Variable	Description	Default
LOGSEQ_DIR	Path to your Logseq graph directory	~/logseq-graph
CACHE_TTL	Cache time-to-live in seconds	300 (5 minutes)

Usage Examples

Search for Notes

"Search my notes for 'machine learning'"

The AI will use search_notes("machine learning") to find relevant content.

Read a Specific Page

"Show me my notes on the Python project"

The AI will use get_page("Python project") to retrieve the page content.

Query by Tag

"What notes do I have tagged with #work?"

The AI will use get_pages_by_tag("work") to list all matching pages.

Journal Entries

"Show me journal entries from last week"

The AI will use get_journal_range("2025-03-25", "2025-03-31") to retrieve entries.

Project Consolidation

"Summarize all my notes for the website redesign project"

The AI will use consolidate_project("website-redesign") to gather all related notes.

Architecture

The server is built on:

• FastMCP: A high-level Python library for building MCP servers
• LogseqIndex: A custom indexing class that:
  • Scans .md files in the Logseq directory
  • Extracts metadata (tags, modification times)
  • Implements incremental updates for efficiency
  • Caches results to minimize I/O operations

Indexing Strategy

The LogseqIndex uses a two-tier caching strategy:

1. File Index Cache: Incrementally updates based on file modification times

   • Full directory scan every CACHE_TTL seconds to detect new/deleted files
   • Fast path for checking only known files between scans

2. Result Cache: Caches tool outputs with configurable TTL per tool

   • Search results: 5 minutes
   • Page content: 1 minute
   • Project consolidation: 10 minutes

Development

Project Structure

.
├── server.py              # Main MCP server implementation
├── pyproject.toml         # Poetry configuration
├── README.md             # This file
├── doc.md                # Installation guide
├── fastmcp_documentation.md  # FastMCP reference
└── command.txt           # Example CLI commands

Running Locally

# Set environment variables
export LOGSEQ_DIR="~/Documents/MyLogseqGraph"
export CACHE_TTL=300

# Run the server
poetry run python server.py

Testing with MCP Inspector

npx @modelcontextprotocol/inspector poetry run python server.py

Requirements

• Python >= 3.10, < 4.0
• fastmcp >= 3.1.1, < 4.0.0

See pyproject.toml for full dependency specifications.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Acknowledgments

• Built with FastMCP by Josh Fell
• Inspired by the Model Context Protocol specification
• Created for integration with Logseq personal knowledge management

---

Note: This is a community project and is not officially affiliated with Logseq or Anthropic.