Provides tools to read, write, query, and search a Logseq knowledge graph via its HTTP API, enabling AI agents to manage pages, blocks, properties, and perform full-text search and Datalog queries.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@logseq-api-mcp search my notes for 'project ideas'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your AI assistant starts every session blind to your Logseq knowledge graph. logseq-api-mcp fixes that: 21 tools to read, write, query, and search your notes — auto-registered the moment you drop a Python file into src/tools/.
Step 1 — Install
git clone https://github.com/gustavo-meilus/logseq-api-mcp.git
cd logseq-api-mcp
uv syncStep 2 — Configure
cp .env.template .env
# open .env and set LOGSEQ_API_ENDPOINT and LOGSEQ_API_TOKENGetting your token: open Logseq, go to Settings → Features → Developer mode, enable HTTP APIs server, and copy the token shown. The default endpoint is http://127.0.0.1:12315/api.
Step 3 — Connect
// ~/.claude/claude_desktop_config.json
{
"mcpServers": {
"logseq-api": {
"command": "uv",
"args": ["run", "--directory", "/path/to/logseq-api-mcp", "python", "src/server.py"],
"env": {
"LOGSEQ_API_ENDPOINT": "http://127.0.0.1:12315/api",
"LOGSEQ_API_TOKEN": "your_token_here"
}
}
}
}Restart Claude Desktop. All 21 tools are live.
Related MCP server: Logseq MCP Server
Tool | What it does |
| Every page with ID, UUID, journal flag, and namespace |
| Hierarchical block tree with IDs, UUIDs, and child counts |
| Pages linking to a target page |
| Full backlink analysis including block-level references |
| Block detail with properties and immediate children |
| Complete page: properties, blocks, DB refs expanded |
| Q&A flashcard pairs from a page and all linked pages |
| Full-text search across blocks, pages, and file names |
| Raw Datalog / DSL queries against the graph |
| Filter pages by property key and optional value |
| All pages under a Logseq namespace |
| Nested tree of namespace pages |
Tool | What it does |
| Create a page with optional properties and format |
| Remove a page permanently |
| Rename a page and update all references |
| Append or replace content on an existing page |
| Add blocks at the end of a page |
| Replace a block's content by UUID |
| Update block content by UUID |
| Insert a child or sibling block relative to another block |
| Delete a block by UUID |
| Set structured properties on a block (DB-mode only) |
Variable | Default | Description |
|
| Logseq HTTP API base URL |
| (required) | Bearer auth token |
|
| Set |
|
| Enable Logseq database-format API paths |
| (empty) | Comma-separated tags — pages with any tag are hidden |
|
| Log level: |
Logseq's newer database format stores graph data in SQLite rather than markdown files. Set LOGSEQ_DB_MODE=true to unlock set_block_properties, UUID-reference resolution in get_all_page_content, and Datalog-powered queries in find_pages_by_property. Tools that do not apply in DB-mode return a clear error rather than silently failing.
Any page tagged with a tag from LOGSEQ_EXCLUDE_TAGS disappears from every read operation. Enforcement runs at query time, so toggling the variable takes effect immediately.
Operation | Behavior when page is excluded |
| Excluded pages absent from the listing |
| Excluded pages and their blocks stripped from results |
| Results post-filtered against excluded page names |
| Results post-filtered |
| Excluded source pages removed |
| Returns |
Create src/tools/my_tool.py. No imports, no registration, no config changes needed. The discovery system picks it up on the next server start.
from typing import List
from mcp.types import TextContent
from src.client.logseq_client import LogseqClient
from src.client.config import LogseqConfig, load_config
from src.logging_setup import get_logger
_log = get_logger(__name__)
async def _run(
client: LogseqClient, config: LogseqConfig, param: str
) -> List[TextContent]:
try:
_log.debug("%s called", __name__)
result = await client.some_api_method(param)
return [TextContent(type="text", text=str(result))]
except Exception as exc:
_log.error("exception in %s: %s", __name__, exc, exc_info=True)
return [TextContent(type="text", text=f"❌ Error: {exc}")]
async def my_tool(param: str) -> List[TextContent]:
"""One-line description — this becomes the MCP tool description."""
cfg = load_config()
return await _run(LogseqClient(cfg), cfg, param)The _run(client, config, ...) pattern keeps the logic testable via FakeLogseqClient in tests/conftest.py. Function names starting with _ are not registered.
uv sync --dev # all deps
uv run --group test pytest tests/ -v # test suite (345 tests)
uv run --group test pytest tests/ --cov=src --cov-fail-under=85 # coverage gate
uv run ruff check --fix && uv run ruff format # lint + format
uv run mypy src/ --ignore-missing-imports # type check
uv run bandit -r src/ # security scan
uv run mcp dev src/server.py # MCP inspectorMIT — see LICENSE.
Made for the Logseq and MCP communities.
This server cannot be deployed
Persistent memory and knowledge graph for AI assistants — keyword + vector + graph search.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Personal context for every AI: search, read, and write back to your private Markdown library.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
