Logseq MCP Tools

# Logseq MCP Tools A Model Context Protocol (MCP) server that provides AI assistants with structured access to your Logseq knowledge graph. ## Overview This project creates an MCP server that allows AI assistants like Claude to interact with your Logseq knowledge base. It provides tools for: - Retrieving a list of all pages - Getting content from specific pages - Generating journal summaries for flexible date ranges - Extracting linked pages and exploring connections ## Installation 1. Clone this repository 2. Install dependencies using npm, yarn, or pnpm: ```bash # Using npm npm install # Using yarn yarn install # Using pnpm pnpm install ``` 3. Copy the environment template and configure your Logseq token: ```bash cp .env.template .env # Edit .env with your Logseq authentication token ``` ## Configuration This project includes a `.env.template` file that you can copy and rename to `.env`. You can find your Logseq auth token by: 1. Opening Logseq 2. Enabling the HTTP API in Settings > Features > Enable HTTP API 3. Setting your authentication token in Settings > Features > HTTP API Authentication Token ## Usage ### Running the MCP Server The server can be started using: ```bash # Using the npm script npm start # Or directly with tsx npx tsx index.ts ``` ### Connecting with Claude #### Claude Desktop Follow the [Claude MCP Quickstart guide](https://modelcontextprotocol.io/quickstart/user): 1. **Important**: Install Node.js globally via Homebrew (or whatever): ```bash brew install node ``` 2. Install the Claude desktop app 3. Open the Claude menu and select "Settings..." 4. Click on "Developer" in the left sidebar, then click "Edit Config" 5. This will open your `claude_desktop_config.json` file. Replace its contents with: ```json { "mcpServers": { "logseq": { "command": "npx", "args": ["tsx", "/path/to/your/index.ts"] } } } ``` **IMPORTANT:** Replace `/path/to/your/index.ts` with the **exact** absolute path to your index.ts file (e.g., `/Users/username/Code/logseq-mcp-tools/index.ts`) 6. Save the file and restart Claude Desktop Now you can chat with Claude and ask it to use your Logseq data: - "Show me my recent journal entries" - "Summarize my notes from last week" - "Find all pages related to [topic]" #### Claude in Cursor Follow the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol): 1. Open Cursor 2. Add a new MCP service from settings 3. Enter the following command: ``` npx tsx "/path/to/index.ts" ``` 4. Give your service a name like "Logseq Tools" Now you can use Claude in Cursor with your Logseq data. #### Claude in Anthropic API (generic) When using the Claude API or CLI tools, you can add the MCP service with: ``` claude mcp add "logseq" npx tsx "/path/to/index.ts" ``` ## Available Tools ### getAllPages Retrieves a list of all pages in your Logseq graph. ### getPage Gets the content of a specific page. Parameters: - `pageName`: The name of the page to retrieve ### getJournalSummary Generates a summary of journal entries for a specified date range. Parameters: - `dateRange`: Natural language date range like "today", "this week", "last month", "this year", etc. This tool will: - Collect journal entries in the specified range - Format them in a readable way - Extract and analyze referenced pages/concepts - Show the most frequently referenced concepts ### createPage Creates a new page in your Logseq graph. Parameters: - `pageName`: Name for the new page - `content`: (Optional) Initial content for the page ### searchPages Searches for pages by name. Parameters: - `query`: Search query to filter pages by name ### getBacklinks Finds all pages that reference a specific page. Parameters: - `pageName`: The page name for which to find backlinks ### analyzeGraph Performs a comprehensive analysis of your knowledge graph. Parameters: - `daysThreshold`: (Optional) Number of days to look back for "recent" content (default: 30) Features: - Identifies frequently referenced pages - Tracks recent updates - Discovers page clusters and connections - Lists outstanding tasks - Suggests potential updates needed ### findKnowledgeGaps Analyzes your knowledge graph to identify potential gaps and areas for improvement. Parameters: - `minReferenceCount`: (Optional) Minimum references to consider (default: 3) - `includeOrphans`: (Optional) Include orphaned pages in analysis (default: true) Features: - Identifies missing pages that are frequently referenced - Finds underdeveloped pages that need expansion - Lists orphaned pages with no incoming links - Provides summary statistics ### analyzeJournalPatterns Analyzes patterns in your journal entries over time. Parameters: - `timeframe`: (Optional) Time period to analyze (e.g., "last 30 days", "this year") - `includeMood`: (Optional) Analyze mood patterns if present (default: true) - `includeTopics`: (Optional) Analyze topic patterns (default: true) Features: - Topic trends and evolution - Mood pattern analysis - Habit tracking statistics - Project progress tracking ### smartQuery Executes natural language queries using Logseq's DataScript capabilities. Parameters: - `request`: Natural language description of what you want to find - `includeQuery`: (Optional) Include the generated Datalog query in results - `advanced`: (Optional) Use advanced analysis features Features: - Page connections and relationships - Content clustering - Task progress analysis - Concept evolution tracking ### suggestConnections Uses AI to analyze your graph and suggest interesting connections. Parameters: - `minConfidence`: (Optional) Minimum confidence score for suggestions (0-1, default: 0.6) - `maxSuggestions`: (Optional) Maximum number of suggestions to return (default: 10) - `focusArea`: (Optional) Topic or area to focus suggestions around Features: - Discovers potential connections between pages - Identifies knowledge synthesis opportunities - Suggests exploration paths based on recent interests - Provides confidence scores for suggestions ## Development The server is built using: - Model Context Protocol TypeScript SDK - Zod for parameter validation - Logseq HTTP API for data access To extend with new tools, add additional `server.tool()` definitions in `index.ts`. ## Troubleshooting ### Common Issues #### Node.js Version Managers (fnm, nvm, etc.) If you're using a Node.js version manager like fnm or nvm, Claude Desktop won't be able to access the Node.js binaries properly, as it runs outside of your shell environment where the PATH is modified. **Solution**: Install a system-wide Node.js with Homebrew: ```bash brew install node ``` This ensures Node.js is available to all applications, including Claude Desktop. #### Basic Troubleshooting Steps - Ensure Logseq is running with the HTTP API enabled - Verify your auth token in `.env` matches the one set in Logseq - Check that the path to your index.ts file is correct in the Claude configuration - Try running `npx tsx index.ts` directly in your terminal to verify it works #### Viewing Logs in Claude Desktop Monitor logs in real-time: ```bash # macOS tail -n 20 -F ~/Library/Logs/Claude/mcp*.log ``` For more detailed debugging information, refer to the [official MCP debugging documentation](https://modelcontextprotocol.io/docs/tools/debugging).