Logseq Model Context Protocol Agent
npm install logseq-mcpA powerful AI assistant that connects Logseq with Claude and other LLMs using the Model Context Protocol (MCP).
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.
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:unitRun e2e tests only
bun test:e2eRun tests in watch mode
bun test:watch
`$3
`bash
Standard build
bun run buildBuild for Node.js
bun run build:nodeBuild for Bun
bun run build:bunBuild 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 requestPlease 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.