Provides tools for reading, creating, and manipulating Logseq content, including block operations, page management, query execution, and journal access.
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-mcp add a block 'Review project updates' to today's journal"
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.
An MCP (Model Context Protocol) server for interacting with Logseq graphs, enabling AI assistants to read, create, and manipulate Logseq content.
Block Operations: Create, update, and delete blocks
Page Management: Create pages, retrieve page content, search pages
Query Execution: Execute Datalog queries against your Logseq graph
Journal Support: Access journal pages by date with automatic format conversion
Privacy-First Logging: Automatic sanitization of sensitive data in logs
MCP Protocol: Full compliance with the Model Context Protocol specification
Related MCP server: Logseq MCP Tools
We provide a setup wizard that will guide you through the installation:
# Clone the repository
git clone https://github.com/yourusername/logseq-mcp.git
cd logseq-mcp
# Run the setup wizard
./deploy.shThe setup wizard will:
Check your Python version (3.13+ required)
Install uv package manager (if not present)
Install all dependencies
Configure your Logseq API connection
Test the connection to Logseq
Generate configuration for Claude Desktop or Cline
Python 3.13+
Logseq with API enabled
uv (recommended) or pip for package management
If you prefer to set up manually instead of using the setup wizard:
# Clone the repository
git clone https://github.com/yourusername/logseq-mcp.git
cd logseq-mcp
# Install dependencies
uv pip install --system -e .
# Install development dependencies (optional)
uv pip install --system -e ".[dev]"# Clone the repository
git clone https://github.com/yourusername/logseq-mcp.git
cd logseq-mcp
# Install dependencies
pip install -e .
# Install development dependencies (optional)
pip install -e ".[dev]"Copy the example environment file:
cp env/.env.example env/.envConfigure your Logseq API settings in env/.env:
LOGSEQ_API_HOST=localhost
LOGSEQ_API_PORT=12315Enable the Logseq API in your Logseq settings
The setup wizard (./deploy.sh) will generate the configuration for you. If you need to configure manually, add the following to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"logseq": {
"command": "uv",
"args": [
"--directory",
"/path/to/logseq-mcp",
"run",
"--with",
".",
"--refresh",
"--python",
"3.13",
"python",
"-m",
"logseq_mcp_server"
],
"env": {
"LOGSEQ_API_HOST": "localhost",
"LOGSEQ_API_PORT": "12315",
"LOGSEQ_MCP_LOG_LEVEL": "INFO",
"LOGSEQ_MCP_PROJECT_ROOT": "/path/to/logseq-mcp"
}
}
}
}Security note: Delete operations are disabled by default to prevent accidental or AI-initiated data loss. Add
"LOGSEQ_DELETE_ENABLED": "true"to theenvblock only when you explicitly want the AI assistant to be able to delete blocks.
Important Notes:
Replace ALL instances of /path/to/logseq-mcp with the actual absolute path to your cloned repository (in args AND env)
The --directory argument sets UV's working directory
The --with . argument tells UV to install the local package before running
The --refresh flag ensures UV uses the latest code (important during development)
The LOGSEQ_MCP_PROJECT_ROOT environment variable ensures logs are saved in the project directory
Ensure Logseq is running with the API server enabled before starting Claude Desktop
You may need to configure authentication if your Logseq API requires a token
To enable the delete_block tool, add LOGSEQ_DELETE_ENABLED to the env block:
"env": {
"LOGSEQ_API_HOST": "localhost",
"LOGSEQ_API_PORT": "12315",
"LOGSEQ_DELETE_ENABLED": "true"
}Troubleshooting:
If you see errors about cached code, run uv cache clean to clear UV's cache
Check logs in the logs/ directory of the project for detailed error information
After updating the configuration, restart Claude Desktop to connect to the Logseq MCP server.
For Cline users, the setup wizard will provide the configuration. You can also manually add the server to your Cline settings in VS Code:
Open VS Code Settings
Navigate to Extensions > Cline > MCP Servers
Add the configuration provided by the setup wizard
The server includes privacy-focused logging that protects your personal data by default:
Default Privacy Mode: Personal data like page names, content, and queries are automatically sanitized
Automatic Log Rotation: Prevents disk space issues with configurable size/time-based rotation
Configurable Retention: Set how long to keep logs before automatic deletion
Privacy Mode (default): Sanitizes sensitive information
Page names: "My Private Notes" → "My P***otes" (preserves partial visibility)
Content: Replaced with [content_123_chars]
Queries: Hidden as [datalog_query_45_chars]
File paths: /Users/john/Documents → /Users/***/Documents
Block IDs: Anonymized to block_a1b2c3 (consistent hashing)
Debug Mode: Full logging for troubleshooting
Enable with LOGSEQ_MCP_LOG_MODE=debug
Shows complete data (use only when needed)
Minimal Mode: Only errors and warnings
Enable with LOGSEQ_MCP_LOG_MODE=minimal
# Environment variables
LOGSEQ_MCP_LOG_MODE=privacy # privacy, debug, or minimal (default: privacy)
LOGSEQ_MCP_LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR (default: INFO)
LOGSEQ_MCP_LOG_RETENTION_DAYS=7 # Days to keep logs (default: none)
LOGSEQ_MCP_LOG_MAX_SIZE=10MB # Max file size before rotation (default: 10MB)
LOGSEQ_MCP_DEBUG=true # Enable console output (default: false)
LOGSEQ_MCP_LOG_FILE=/custom/path.log # Custom log location (optional){
"timestamp": "2025-01-15T10:30:45Z",
"level": "INFO",
"logger": "logseq_mcp_server.logging_config",
"message": "Tool get_page completed successfully",
"tool_name": "get_page",
"arguments": {
"name": "My P***nal"
},
"result": {
"success": true,
"page": {
"originalName": "My P***nal",
"uuid": "block_7d4e8c"
}
},
"duration_ms": 45
}# View logs in real-time
tail -f logs/logseq-mcp.log
# Search logs while respecting privacy
grep '"level": "ERROR"' logs/logseq-mcp.logWhen troubleshooting issues:
# Run with debug logging temporarily
LOGSEQ_MCP_LOG_MODE=debug python -m logseq_mcp_server
# Or in Claude Desktop config (temporarily):
"env": {
"LOGSEQ_MCP_LOG_MODE": "debug",
"LOGSEQ_MCP_LOG_RETENTION_DAYS": "1"
}Important: Remember to switch back to privacy mode after debugging to protect your personal data.
# Run with default stdio transport
python -m logseq_mcp_server
# Run with SSE transport
LOGSEQ_MCP_TRANSPORT=sse python -m logseq_mcp_server
# Run with MCP CLI
mcp run src/logseq_mcp_server/server.pycreate_block: Create a new block in a page
update_block: Update an existing block's content or properties
delete_block: Delete a block (disabled by default; requires LOGSEQ_DELETE_ENABLED=true)
create_page: Create a new page
get_all_pages: Get all pages in the current graph
get_page: Retrieve a page and its content
get_journal_page: Get a journal page by date (supports various date formats)
search_pages: Search for pages by query
execute_query: Execute Datalog queries (supports optional input parameters for parameterized queries)
The get_journal_page tool provides a convenient way to retrieve journal pages by date, automatically converting various date formats to Logseq's journal page naming convention.
The tool accepts dates in multiple formats:
ISO format: "2023-12-25"
US format: "12/25/2023"
EU format: "25/12/2023"
Abbreviated pre-formatted: "Dec 25th, 2023"
Python date/datetime objects (when using the API directly)
// Get today's journal page
{
"tool": "get_journal_page",
"arguments": {
"date": "2024-01-15"
}
}
// Get journal with blocks
{
"tool": "get_journal_page",
"arguments": {
"date": "01/15/2024",
"include_children": true
}
}The tool converts the provided date to Logseq's abbreviated journal format (e.g., "Dec 25th, 2023") before fetching the page.
The execute_query tool runs Datalog queries against the graph. It also accepts an optional inputs array for parameterized queries.
// Simple query
{
"tool": "execute_query",
"arguments": {
"query": "[:find ?name :where [?p :block/name ?name]]"
}
}
// Parameterized query
{
"tool": "execute_query",
"arguments": {
"query": "[:find ?b :in $ ?tag :where [?b :block/refs ?r] [?r :block/name ?tag]]",
"inputs": ["meeting"]
}
}If you encounter issues during setup:
Python Version: Ensure you have Python 3.13+ installed
python3 --versionLogseq API: Make sure the API server is enabled in Logseq:
Settings > Advanced > Enable "API Server"
Default port is 12315
Connection Issues: Test the connection manually:
cd logseq-mcp
python tests/tools/test_logseq.py get-all-pages --limit 5Logs: Check the logs directory for detailed error information:
tail -f logs/logseq-mcp.logClean Install: If all else fails, try a clean installation:
# Remove existing installation
rm -rf .venv build dist *.egg-info
# Run setup wizard again
./deploy.shA standalone test harness (tests/tools/test_logseq.py) is provided for rapid testing and debugging of Logseq API calls without going through the MCP protocol. This tool is useful for:
Debugging API connectivity issues
Testing raw API methods directly
Exploring Logseq API capabilities interactively
Verifying API responses before implementing MCP tools
Usage examples:
# Test specific methods
python tests/tools/test_logseq.py get-page "MCP Server"
python tests/tools/test_logseq.py get-page "Test Page" --show-raw
python tests/tools/test_logseq.py get-all-pages --limit 5
python tests/tools/test_logseq.py search "test"
# Test journal pages
python tests/tools/test_logseq.py get-page "December 25th, 2023" # Get journal by formatted name
# Raw API calls
python tests/tools/test_logseq.py raw logseq.Editor.getCurrentGraph
python tests/tools/test_logseq.py raw logseq.Editor.getPage "My Page"
# Interactive REPL mode
python tests/tools/test_logseq.py interactive
# Verbose mode for debugging
python tests/tools/test_logseq.py get-page "MCP Server" --verboseThe test harness provides:
Direct access to LogseqClient without MCP overhead
Pretty-printed JSON output
Interactive REPL for exploration
Full request/response logging
Command history in interactive mode
Most Logseq API methods expect arguments to be wrapped in arrays, even for single values:
Correct: logseq.Editor.getPage ["MCP Server"]
Incorrect: logseq.Editor.getPage "MCP Server"
Methods that require array format: getPage, getPageBlocksTree, getBlock, removeBlock, createPage, insertBlock, updateBlock. Methods that use string format: search, q (queries).
# Run all tests
pytest
# Run with coverage
pytest --cov=src/logseq_mcp_server tests/
# Run specific test
pytest tests/unit/test_tools.py -v# Run linter
ruff check src/ tests/
# Format code
ruff format src/ tests/Fork the repository
Create a feature branch (git checkout -b feat/amazing-feature)
Commit your changes using conventional commits
Push to the branch (git push origin feat/amazing-feature)
Open a Pull Request
This project uses conventional commits. Examples:
feat(tools): add block creation tool
fix(api): handle empty query results
docs(readme): update installation instructions
See CLAUDE.md for detailed development guidelines.
This project is private and proprietary. All rights reserved.
Create a new block in Logseq
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | The page to create the block in | |
| content | Yes | The content of the block | |
| properties | No | Optional block properties | |
| parent_block_id | No | Optional parent block ID for nested blocks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It transparently says the tool creates a block, which implies a write operation but doesn't disclose side effects, error conditions, or whether existing content in the page is modified. The description is minimal but not misleading; it just lacks depth about what 'create' entails in Logseq.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
At six words, it is extremely concise and front-loaded. Every word carries meaning, and there is no filler. However, it is so brief that it doesn't provide any context beyond the tool name's obvious meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with no output schema and no annotations, the description is thin. It doesn't explain the expected page identifier format (name vs UUID), whether properties are optional or how they are structured, whether parent_block_id must reference an existing block, or what success/failure looks like. The tool's complexity (4 params, nested objects) demands more guidance than this single sentence provides.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents all parameters with descriptions. The description adds no parameter detail beyond what's in the schema, but baseline 3 applies because the schema already covers the semantics of page, content, properties, and parent_block_id. The description doesn't clarify the format of properties or parent_block_id relationships, but with full coverage, that is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Create a new block in Logseq', which is a specific verb and resource, and it is distinguishable from the closely related update_block and create_page. However, it doesn't elaborate on what creating a block entails or how it differs from create_page beyond the resource type, which is already evident from the names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that create_page is for pages while this is for blocks, nor does it state any prerequisites like needing an existing page or page identifier format. An agent is left to infer usage context from the parameter names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new page in Logseq
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the page | |
| content | No | Optional initial content for the page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It only restates the create action and gives no detail about side effects, duplicate-page behavior, whether content replaces or appends, or whether the operation has any irreversible consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant wording. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only 2 parameters and no output schema, so the minimal description is partially adequate. However, the lack of annotations and absence of behavioral context around duplicates or effects leaves minor but real gaps for an agent deciding whether and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter meaning, but the schema already documents 'name' as the page name and 'content' as optional initial content, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create'), the resource ('page'), and the context ('Logseq'). It also distinguishes this tool from siblings like create_block (block creation) and get/update/search operations, so an agent can easily identify what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as create_block or update_block. It does not state exclusions, prerequisites, or scenarios where another sibling should be preferred, leaving the agent to infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a Datalog query in Logseq
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The Datalog query to execute | |
| inputs | No | Optional query inputs/parameters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action without revealing whether the tool is read-only, what side effects it may have, how errors are handled, or any limits on query execution. The agent is left entirely in the dark about the operation's behavior beyond the literal verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence communicates the core purpose with zero excess words. Every element is relevant, and there is no redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description is too sparse to be fully contextual. It does not explain what the query returns, whether it mutates state, or how inputs are used. For a simple two-parameter tool this is a notable but not fatal gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents both `query` and `inputs`. The description adds no additional meaning about parameter formats, defaults, or relationships, but it does not need to because the schema covers everything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Execute'), a specific resource ('a Datalog query in Logseq'), and is clearly distinguishable from the sibling tools, which are all page/block CRUD operations. An agent can immediately tell this is the querying tool without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It does not mention that this is the right choice for read-only analysis or that it differs from page/block manipulation. The only context is implied by the tool's name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all pages in the current Logseq graph
| Name | Required | Description | Default |
|---|---|---|---|
| include_journals | No | Whether to include journal pages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It clearly signals a read-only listing operation and the graph scope, but it does not state the return shape, pagination behavior, or that journal pages are included by default; that default only appears in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short front-loaded sentence with no filler. Every word contributes the operation, scope, or resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema covers its only parameter, but there is no output schema and no usage guidance, so the agent is left without information about the returned page objects or when to prefer sibling tools. Adequate for a basic listing, but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is fully documented in the schema (100% coverage), including its default value. The description adds no extra meaning about include_journals, so it neither improves nor harms parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: get all pages in the current Logseq graph. The 'all' scope distinguishes it from single-page tools like get_page and get_journal_page, though it does not explicitly name alternatives like search_pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus its siblings. It does not say to use search_pages for filtered/query-based page lookup or get_page for a single page, so the agent must infer routing from names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a journal page by date. Automatically converts the date to Logseq's journal format.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | The date for the journal page. Accepts various formats: ISO (2023-12-25), US (12/25/2023), or already formatted (December 25th, 2023) | |
| include_children | No | Whether to include child blocks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description is the only behavioral signal. It discloses one useful behavior — automatic conversion of the input date to Logseq's journal format. However, it does not address what happens if the page does not exist, whether any write side effects occur, or what the return payload contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences convey the core purpose and a key behavior with no filler. The most important information is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity getter with fully described parameters, the description and schema together are sufficient for invoking the tool correctly. The lack of an output schema and any mention of the response or missing-page behavior leaves modest gaps, though not enough to impede correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both date and include_children with full descriptions (100% coverage), so the baseline is 3. The description adds extra value by explicitly noting that dates are converted into Logseq journal format, which elaborates on the date parameter beyond the schema's accepted-formats list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get'), a specific resource ('journal page'), and the key selection criterion ('by date'), which clearly separates it from siblings like get_page or search_pages. The additional note about date conversion reinforces the tool's unique scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the intended use case (obtaining a journal page on a given date), but does not explicitly contrast it with alternatives such as get_page or search_pages, nor state when not to use it. The usage context is clear enough to infer, but no exclusions or routing guidance is included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a page from Logseq by name
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the page to retrieve | |
| include_children | No | Whether to include child blocks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It only says 'Get', giving no detail about return format, exact-match/case sensitivity, behavior when the page does not exist, or the effect of the include_children default. This is thin for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is efficient and front-loads the action and object before the qualifier. There is no filler, though the brevity contributes to the behavioral gaps penalized in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with no annotations and no output schema, the definition does not explain what a returned page contains, what format 'name' expects, or the implications of include_children defaulting to true. The sibling set also makes the lack of routing guidance more costly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented. The phrase 'by name' aligns with the required name parameter but adds no extra meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), resource ('a page'), and the lookup mechanism ('by name'), which distinguishes it from get_all_pages and get_journal_page. It does not explicitly name sibling alternatives, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to use this tool versus get_journal_page, search_pages, or get_all_pages. 'By name' implies the input condition, but there is no context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for pages in Logseq
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return | |
| query | Yes | The search query |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the operation and gives no information about matching behavior, result format, pagination, ordering, or any side effects. This is a significant gap for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is concise, though it is so minimal that it adds little beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain what results look like or what 'search' matches against. It does neither, leaving the agent to guess about return values and behavior. This is inadequate for a tool with several closely related siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters 'query' and 'limit' are already documented. The description adds no additional meaning beyond what the schema provides, which aligns with the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search'), resource ('pages'), and context ('Logseq'). It is clear what the tool does, though it does not explicitly contrast itself with sibling tools like get_all_pages or get_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as get_all_pages, get_page, or execute_query. The only implied usage is that this tool searches pages, but no exclusions or selection criteria are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing block in Logseq
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | The new content for the block | |
| block_id | Yes | The ID of the block to update | |
| properties | No | Optional updated block properties |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'update' without detailing mutation semantics, whether the update is partial or full replacement, what happens if the block_id doesn't exist, or whether properties are merged or overwritten. This is a significant transparency gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler. It is front-loaded and easy to parse, though it is terse and could benefit from slightly more context without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a mutation tool with no annotations and no output schema. It omits key context such as whether the update replaces or merges content, how properties behave, error handling, and return values, leaving an agent without enough information to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all three parameters. The description adds no additional parameter-level meaning, but per the baseline, a 3 is appropriate when the schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the specific operation 'update' and the resource 'block' in Logseq, which distinguishes it from sibling tools like create_block and page-focused tools. It is unambiguous and directly states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. The word 'existing' implies it is for pre-existing blocks rather than creation, but no explicit when-to-use or when-not-to-use context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0create_blockcreate_pageexecute_queryget_all_pagesget_journal_pageget_pagesearch_pagesupdate_blockScored across 8 tools
Each tool targets a distinct operation: page retrieval, page creation, block creation/update, journal fetching, search, and querying. The only potentially related tools are get_page, get_all_pages, and search_pages, but their purposes are clearly differentiated by exact-match retrieval, full listing, and search.
All tools follow a consistent verb_noun pattern in snake_case, such as create_block, get_page, search_pages, and execute_query. The naming convention is uniform and predictable throughout the entire set.
Eight tools is well-scoped for a Logseq MCP server, covering page management, block manipulation, search, and querying without unnecessary bloat. Each tool has a clear role in the surface.
The server covers creation and reading for pages and creation/update for blocks, but missing operations like page update/delete, block delete, or block retrieval create notable gaps. Agents can work around some of these via execute_query, but lifecycle coverage is incomplete.
MCP server for AI dialogue using various LLM models via AceDataCloud
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
