Logseq MCP Agent

A powerful AI assistant that connects Logseq with Claude and other LLMs using the Model Context Protocol (MCP).

What is it?

Logseq MCP Agent lets AI assistants like Claude directly interact with your Logseq knowledge graph - search your notes, create content, organize information, and manage tasks.

MCP (Model Context Protocol) works like a "USB-C port for AI" - providing a standardized way for AI models to connect with your applications and data. This agent implements MCP to give Claude and other LLMs a direct, structured interface to your Logseq knowledge base.

Think of it as giving Claude direct access to your second brain.

Key Features

$3

- Search your entire graph for information
- Generate summaries of pages and content
- Create daily notes with custom sections
- Organize flat pages into nested structures

$3

- Find all tasks with specific statuses (TODO, DOING, etc.)
- Extract tasks from meeting notes
- Create and organize task lists
- Track task progress

$3

- Natural language search across your graph
- Find blocks by content
- Run advanced Datalog queries

$3

- Restructure content hierarchically
- Organize blocks by any criteria
- Transform flat content into nested structures

Quick Setup

$3

- Logseq with HTTP API enabled
- A Logseq API token
- Claude Desktop or other MCP-compatible AI assistant

$3

1. In Logseq → Settings → Advanced: Enable "Developer mode"
2. Restart Logseq
3. In Settings: Enable "HTTP API server"
4. Copy your API token

$3

1. Open Claude Desktop settings
2. Navigate to MCP Servers
3. Add a new server:
``json
{
"mcpServers": {
"logseq": {
"command": "npx",
"args": [
"logseq-mcp"
],
"env": {
"LOGSEQ_TOKEN": "your_logseq_token"
}
}
}
}
`
4. Replace your_logseq_token with your actual token
5. Save and restart Claude

$3

Try asking:
- "Find all my TODO tasks in Logseq"
- "Create a daily note with sections for Tasks, Notes, and Journal"
- "Summarize my 'Research' page"
- "Search my notes for information about machine learning"

Alternative Installation

Install via npm:
`bash
npx logseq-mcp
`

Or install globally:
`bash
npm install -g logseq-mcp
`

Configure with a .env file:
`
LOGSEQ_PORT=12315
LOGSEQ_HOST=127.0.0.1
LOGSEQ_TOKEN=your_logseq_token
`

Run with:
`bash
logseq-mcp
`

Troubleshooting

- Ensure Logseq is running before starting the agent
- Verify your API token is correct
- Check that the Logseq HTTP API is enabled
- Try debug mode: DEBUG=true logseq-mcp

$3

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with:

`bash
npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-logseq run mcp-logseq
`

Technical Details

Built using the Model Context Protocol (MCP), an open standard for connecting AI models with external tools and data sources. The agent acts as an MCP server that provides structured access to your Logseq graph via the Logseq HTTP API.

Development

$3

1. Clone the repository:
`bash
git clone https://github.com/briansunter/logseq-mcp.git
cd logseq-mcp
`

2. Install dependencies:
`bash
# Using npm
npm install

# Using Bun (recommended)
bun install
`

$3

The project includes unit and end-to-end tests:

`bash


Run all tests

bun test tests/

Run unit tests only

bun test:unit

Run e2e tests only

bun test:e2e

Run tests in watch mode

bun test:watch
`

$3

`bash


Standard build

bun run build

Build for Node.js

bun run build:node

Build for Bun

bun run build:bun

Build binaries for various platforms

bun run build:binary # Current platform
bun run build:macos-arm # macOS ARM
bun run build:macos-intel # macOS Intel
bun run build:linux-x64 # Linux x64
bun run build:linux-arm64 # Linux ARM64
bun run build:windows # Windows
bun run build:all-binaries # All platforms
`

$3

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Commit your changes: git commit -m 'Add some feature'
4. Push to the branch: git push origin feature/your-feature-name
5. Submit a pull request

Please make sure your code passes all tests and follows the existing code style. Add tests for new features.

Contributing & License

Contributions welcome! MIT License.

Contributing

$3

This project uses semantic-release to automatically manage version numbers and create GitHub releases. Version numbers are determined by PR titles using the following conventions:

| PR Title Format | Example | Result |
|-----------------|---------|--------|
| feat: ... | feat: add new search feature | Minor version increase (0.X.0) |
| fix: ... | fix: resolve search bug | Patch version increase (0.0.X) |
| feat(breaking): ... | feat(breaking): change API format | Major version increase (X.0.0) |

Other valid prefixes: docs:, style:, refactor:, perf:, test:, chore:, ci:, build:` (all result in patch versions).

When merging PRs to master, please follow these conventions in your PR titles to ensure proper versioning.