# logseq-mcp-server
A TypeScript [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects AI assistants to your [Logseq](https://logseq.com/) knowledge graph. Read, write, search, and manage pages, blocks, journals, and tags through the MCP protocol.
## Features
- **17 tools** covering Pages, Blocks, Search, Journals, and Graph operations
- Full CRUD for pages and blocks
- Full-text search across the graph
- Batch block insertion with nested children
- Block property management
- Backlink (linked references) retrieval
- Journal page creation and tag listing
- **Dual transport**: stdio (local) and HTTP ([Hono](https://hono.dev/)-based, portable across runtimes)
## Prerequisites
1. **Logseq** installed and running
2. **HTTP APIs server** enabled in Logseq:
- Settings > Features > Enable "HTTP APIs server"
- Click the API button > "Start server"
- Generate a token: API panel > Authorization tokens
3. **Node.js** >= 18
## Quick Start
### Claude Desktop
Add to `Settings > Developer > Edit Config`:
```json
{
"mcpServers": {
"logseq": {
"command": "npx",
"args": ["logseq-mcp-server"],
"env": {
"LOGSEQ_API_TOKEN": "your_token_here"
}
}
}
}
```
### Claude Code
```bash
claude mcp add logseq-mcp-server \
--env LOGSEQ_API_TOKEN=your_token_here \
-- npx logseq-mcp-server
```
### From Source
```bash
git clone https://github.com/user/logseq-mcp-server.git
cd logseq-mcp-server
npm install
npm run build
LOGSEQ_API_TOKEN=your_token npm start
```
## Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| `LOGSEQ_API_TOKEN` | Yes | - | Bearer token from Logseq HTTP API |
| `LOGSEQ_API_URL` | No | `http://127.0.0.1:12315` | Logseq HTTP API URL |
| `TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
| `PORT` | No | `3000` | HTTP port (when `TRANSPORT=http`) |
## HTTP Transport
When running with `TRANSPORT=http`, the server uses [Hono](https://hono.dev/) with `WebStandardStreamableHTTPServerTransport` from the MCP SDK.
```bash
LOGSEQ_API_TOKEN=your_token TRANSPORT=http PORT=3000 npm start
```
Endpoints:
- `POST|GET|DELETE /mcp` - MCP Streamable HTTP protocol
- `GET /health` - Health check
```bash
curl http://localhost:3000/health
# {"status":"ok","server":"logseq-mcp-server"}
```
## Available Tools
### Pages
| Tool | Description |
|---|---|
| `logseq_list_pages` | List pages with filtering (journal, namespace) and pagination |
| `logseq_get_page` | Get page metadata by name or UUID |
| `logseq_get_page_content` | Get full block tree rendered as indented Markdown |
| `logseq_create_page` | Create a new page with optional initial content and properties |
| `logseq_delete_page` | Permanently delete a page |
| `logseq_rename_page` | Rename a page (updates all references) |
| `logseq_get_page_linked_references` | Get backlinks - pages and blocks that reference a page |
### Blocks
| Tool | Description |
|---|---|
| `logseq_get_block` | Get a block by UUID with optional children |
| `logseq_insert_block` | Insert a block relative to a page or block |
| `logseq_append_block` | Append a block at the end of a page |
| `logseq_update_block` | Update block content and properties |
| `logseq_remove_block` | Permanently remove a block |
| `logseq_move_block` | Move a block to a new position |
| `logseq_insert_batch_blocks` | Insert multiple blocks at once (supports nesting) |
| `logseq_block_property` | Read or write a single block property |
### Search & Graph
| Tool | Description |
|---|---|
| `logseq_search` | Full-text search across pages and blocks |
| `logseq_create_journal` | Create a journal page for a specific date |
| `logseq_get_graph_info` | Get current graph name and path |
| `logseq_get_all_tags` | List all tags in the graph |
## Architecture
```
src/
├── index.ts # Entry point, server init, transport selection
├── constants.ts # Shared constants
├── types.ts # TypeScript type definitions
├── schemas/
│ └── index.ts # Zod input validation schemas
├── services/
│ ├── logseq-client.ts # Logseq HTTP API client
│ └── formatters.ts # Response formatting helpers
└── tools/
├── page-tools.ts # Page CRUD tools
├── block-tools.ts # Block CRUD tools
└── search-graph-tools.ts # Search, journal, graph tools
```
```
MCP Client (Claude, etc.)
↓ stdio or HTTP
MCP Server (index.ts, Hono)
↓ registers tool groups
Tools (page-tools, block-tools, search-graph-tools)
↓ calls service methods
LogseqClient (logseq-client.ts)
↓ POST /api { method, args }
Logseq HTTP API (local instance)
```
## Development
```bash
npm install # Install dependencies
npm run build # Compile TypeScript
npm run dev # Watch mode (tsc --watch)
npm run inspect # Test with MCP Inspector
```
## License
Apache-2.0
