Skip to main content
Glama

Lunatask MCP Server

Lunatask MCP is an unofficial Model Context Protocol server that provides a standardized bridge between AI models and the Lunatask API. It's designed as a lightweight, asynchronous Python application using the FastMCP framework, running as a local subprocess to enable AI tools to interact with Lunatask data.

Important Notes

End-to-End Encryption

Lunatask uses end-to-end encryption for sensitive task and note data. As a result:

  • Task name/note fields and note content are not included in API responses

  • Only non-sensitive metadata and structural information is available

  • This is a security feature of Lunatask and cannot be bypassed

  • The name, note, and content fields can be included in create requests

  • Lunatask automatically encrypts these fields client-side before storage

  • Once created, these fields will not be visible in GET responses due to E2E encryption

  • This is normal Lunatask behavior and ensures data privacy

Task IDs

  • Task IDs are unique identifiers assigned by Lunatask

  • Use the All Tasks resource to discover available task IDs

  • Task IDs remain consistent across API calls

Rate Limiting
  • The server implements rate limiting to prevent API abuse

  • If you encounter rate limit errors, wait before retrying

  • Rate limits are per-server instance and reset over time

Related MCP server: Streamline MCP

Local Installation

Lunatask MCP Server is managed by uv, so you will need to install it.

Using uv

# Install dependencies and create the local virtual environment
uv sync

# Optionally verify the package imports correctly
uv run python -c "import lunatask_mcp"

Server Configuration

The Lunatask MCP server supports flexible configuration through TOML files and command-line arguments. A bearer token is required to authenticate with the Lunatask API.

Quick Start

  1. Copy the example configuration file to a path you prefer:

cp config.example.toml ~/path/to/your/lunatask_mcp_config.toml
  1. Edit the copied configuration file and add your Lunatask API bearer token:

lunatask_bearer_token = "your_lunatask_bearer_token_here"
  1. Run the server:

uv run lunatask-mcp --config-file /path/to/your/config.toml

Note: To create an access token open Lunatask app, open application settings, head to "Access tokens" section, and create a new access token. Then, click "Copy to clipboard", and paste it in the lunatask_bearer_token field in the config file.

Configuration Methods

The server supports three configuration methods with the following precedence (highest to lowest):

  1. Command-line arguments (highest priority)

  2. Configuration file (TOML format)

  3. Default values (lowest priority)

Command-Line Usage

# Basic usage with default config file (./config.toml)
uv run lunatask-mcp

# Specify a custom config file
uv run lunatask-mcp --config-file /path/to/your/config.toml

# Override specific settings (examples)
uv run lunatask-mcp --log-level DEBUG --port 9000
uv run lunatask-mcp --base-url https://api.lunatask.app/v1/
uv run lunatask-mcp --token "$LUNATASK_TOKEN"
uv run lunatask-mcp --rate-limit-rpm 120 --rate-limit-burst 20

# Get help on available options
uv run lunatask-mcp --help

Configuration File Format

Create a config.toml file with your settings:

# Required: Your Lunatask API bearer token
lunatask_bearer_token = "your_lunatask_bearer_token_here"

# Optional: API base URL (default: https://api.lunatask.app/v1/)
lunatask_base_url = "https://api.lunatask.app/v1/"

# Optional: Port for future HTTP transport (default: 8080, range: 1-65535)
# Note: Currently unused as server only supports stdio transport
port = 8080

# Optional: Logging level (default: INFO)
# Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL
log_level = "INFO"

# Optional: Connectivity test during startup (default: false)
test_connectivity_on_startup = false

# Optional: Rate limiting (defaults: rpm=60, burst=10)
rate_limit_rpm = 60
rate_limit_burst = 10

# Optional: HTTP client tuning
# Number of additional retry attempts for transient failures (default: 2)
http_retries = 2
# Initial retry backoff delay in seconds; doubles with each retry (default: 0.25)
http_backoff_start_seconds = 0.25
# Minimum delay before mutating requests (POST/PATCH/DELETE); set to 0.0 to disable (default: 0.0)
http_min_mutation_interval_seconds = 0.0
# Custom User-Agent header advertised to the Lunatask API
http_user_agent = "lunatask-mcp/0.2.1"
# Timeout in seconds for establishing the TLS connection
timeout_connect = 5.0
# Timeout in seconds for reading the response body
timeout_read = 30.0

Configuration Discovery

  • If --config-file is not specified, the server looks for ./config.toml

  • Missing configuration files are only an error if explicitly specified

  • Default values are used when no configuration file exists

Configuration Validation

The server validates all configuration on startup and fails fast with clear error messages:

  • Invalid TOML syntax: Clear parsing error with file location

  • Unknown configuration keys: Rejected with list of unknown keys

  • Invalid values: Port must be 1-65535, URL must be HTTPS, log level must be valid

  • Missing bearer token: Required field, server will not start without it

Security Features

  • Bearer tokens are never logged: Automatically redacted in all log output and error messages

  • Effective configuration logging: Server logs the final configuration with secrets redacted

  • Unknown keys rejection: Prevents typos and ensures clean configuration

  • Input validation: All configuration values are validated before server startup

Server Capabilities

The server provides the following tools:

  • Ping Tool: A health-check tool that responds with "pong" when called

  • MCP Resources (read-only): Discovery + single task, plus area/global list aliases

  • MCP Tools (write): Create, update, delete tasks; create notes; create journal entries; create, delete people; create person timeline notes; track habit activity

  • MCP Protocol Version: Supports MCP protocol version 2025-06-18

  • Stdio Transport: Communicates over standard input/output streams

MCP Client Compatibility

MCP resources depend on the client UI, and many popular MCP clients still surface tools only. As tracked in issue #14, missing resource support remains the main friction when browsing Lunatask data through MCP clients. The official MCP client matrix lists feature coverage. Clients such as Claude Desktop, Claude Code, Cline, Continue, Roo Code, Sourcegraph Cody, and the VS Code MCP extension expose resources today. Editors like Cursor, Windsurf, OpenSumi, and several others show tools only until they add resource support. Choose a resource-capable client when you need to inspect task lists directly.

Tools Available

  • create_task: Creates a new task. Requires name and the target area_id. Optional fields include text content (note), planning data (status, scheduled_on, estimate, progress), prioritisation (priority, motivation, eisenhower), goal context (goal_id) and external source metadata (source, source_id). Returns { "success": true, "task_id": "..." } with the new identifier.

  • create_note: Creates a new note. Accepts notebook_id, name, optional content, date_on, and source/source_id metadata to guarantee idempotency. Returns { "success": true, "note_id": "..." } when created, or { "success": true, "duplicate": true, "message": "Note already exists for this source/source_id" } when the Lunatask API responds with 204 No Content for duplicates.

  • update_note: Updates an existing note by ID. Requires note_id and at least one optional field to update: name, content, notebook_id, or date_on (YYYY-MM-DD format). Supports partial updates—only provided fields are modified. Note that content replaces the entire content due to end-to-end encryption. Returns { "success": true, "note_id": "...", "message": "Note updated successfully", "note": {...} } on success. Validation, not found, authentication, rate limit, timeout, and network errors map to structured error payloads.

  • delete_note: Permanently deletes a note from Lunatask. Requires note_id. Returns { "success": true, "note_id": "...", "deleted_at": "...", "message": "Note deleted successfully" } on success. Note: deletion is not idempotent - attempting to delete the same note twice will return a not found error. Validation, authentication, rate limit, timeout, and network errors map to structured error payloads.

  • create_journal_entry: Creates a journal entry for a specific date. Requires date_on in YYYY-MM-DD format and supports optional name and content (Markdown). Returns { "success": true, "journal_entry_id": "..." } when Lunatask returns a wrapped journal_entry. Responses never include name or content because of end-to-end encryption.

  • create_person: Creates a new person/contact. Requires first_name and last_name. Optional fields include relationship_strength (one of family, intimate-friends, close-friends, casual-friends, acquaintances, business-contacts, or almost-strangers; defaults to casual-friends), external source metadata (source, source_id), and contact details (email, birthday, phone). Returns { "success": true, "person_id": "..." } when created, or { "success": true, "duplicate": true, "message": "Person already exists for this source/source_id" } when Lunatask responds with 204 No Content for duplicates. Note: Custom fields for email, birthday, or phone must be defined in the Lunatask app first, otherwise returns a 422 validation error.

  • create_person_timeline_note: Creates a timeline note for an existing person. Requires person_id and content, accepts an optional date (YYYY-MM-DD). When date is omitted the Lunatask API stores the note against the current day. Returns { "success": true, "person_timeline_note_id": "..." } on success. Validation, authentication, subscription, rate limit, timeout, and network errors map to structured error payloads, and invalid ISO dates are rejected client-side before hitting the API.

  • delete_person: Deletes a person/contact from Lunatask. Requires person_id. Returns { "success": true, "person_id": "...", "deleted_at": "...", "message": "Person deleted successfully" } on success. Note: deletion is not idempotent - attempting to delete the same person twice will return a not found error. Validation, authentication, rate limit, timeout, and network errors map to structured error payloads.

  • update_task: Updates an existing task by ID. Supports partial updates—only the fields you pass (same set as create, minus the required name) are mutated. Returns { "success": true, "task": {...} } with the full serialized task payload.

  • delete_task: Permanently deletes a task from Lunatask. Returns { "success": true, "task_id": "..." }. Deleted tasks cannot be recovered, so invoke with caution.

  • track_habit: Logs habit activity for a specific habit ID and ISO date. Returns { "ok": true, "message": "Successfully tracked habit <id> on <date>" } when the API confirms the event.

Resources Available

The server also has the following resources:

  • Discovery: lunatask://tasks and lunatask://tasks/discovery

  • Single Task: lunatask://tasks/{task_id}

  • Area lists (replace {area_id}):

    • lunatask://area/{area_id}/now

    • lunatask://area/{area_id}/today

    • lunatask://area/{area_id}/overdue

    • lunatask://area/{area_id}/next-7-days

    • lunatask://area/{area_id}/high-priority

    • lunatask://area/{area_id}/recent-completions

  • Global lists:

    • lunatask://global/now

    • lunatask://global/today

    • lunatask://global/overdue

    • lunatask://global/next-7-days

    • lunatask://global/high-priority

    • lunatask://global/recent-completions

Discovery resource returns discovery metadata for list resources, including supported parameters, alias URIs, canonical examples, defaults, and guardrails.

You can filter globally and by area_id. The filters work as follows:

  • today: scheduled today

  • overdue: scheduled before today

  • next-7-days: scheduled within the next 7 days (UTC), excluding today

  • recent-completions: tasks completed in the last 72 hours.

  • now: one of the following:

    • Tasks without scheduled date but with status as "started" (in progress in the app)

    • Tasks without scheduled date but with highest priority (2)

    • Tasks without scheduled date but with motivation as "must"

    • Tasks without scheduled date but with eisenhower as 1 (urgent and important)

Note: There is slight difference between the now in Lunatask and now here. This can create some confusion. Currently, now is seen as urgent and not scheduled. This will be solved in this future issue.

The reason behind these filters is that if you try to gather all the tasks from the Lunatask API you will easily fill up your LLM context if you have a lot of tasks. In the future these could be expanded to include:

  • filters by goal_id

  • filters for all priority types

  • filters for all motivation types

  • filters for all eisenhower types

  • filters for specific dates

  • filters for completed tasks in a range of dates

Integration with other tools

Claude Code

You give access to Claude Code via:

claude mcp add lunatask-mcp -- uvx --from git+https://github.com/tensorfreitas/lunatask-mcp lunatask-mcp --config-file /your/path/to/lunatask_mcp_config.toml

Claude Desktop or LM Studio

{
    "mcpServers": {
        "lunatask-mcp": {
            "command": "uvx",
            "args": ["--from", "git+https://github.com/tensorfreitas/lunatask-mcp", "lunatask-mcp", "--config-file", "/your/path/to/lunatask_mcp_config.toml"]
        }
    }
}

Codex

Unlike Claude Code, in Codex you add an MCP server globally and not per project. Add the following to ~/.codex/config.toml (create the file if it does not exist):

[mcp_servers.lunatask-mcp]
command = "uvx"
args = ["--from", "git+https://github.com/tensorfreitas/lunatask-mcp", "lunatask-mcp", "--config-file", "/your/path/to/lunatask_mcp_config.toml"]

Known Issues

As discussed in MCP Client Compatibility, some MCP clients do not yet implement the full MCP resource surface. The following clients currently connect but only display tools:

  • Codex

  • Gemini CLI

  • LM Studio

  • Qwen CLI

Track progress in issue #14. Tools stay available in these clients while resource views are pending.

To Be Implemented

  1. Implementation of MCP Server-Sent Events (SSE) for HTTP-based clients

  2. Extra Task Resource Filters

  • resource filters by goal_id

  • filters for all priority types

  • filters for all motivation types

  • filters for all Eisenhower types

  • filters for specific dates

  • filters for completed tasks in a range of dates

  1. Extra tools

  1. Extra Resources

Disclaimer

This project was developed with the assistance of AI. The purpose was to test various workflows using different LLMs and identify the most effective approach for me. Since I’m doing this on my free time, this was the only feasible option. Consequently, some of the documentation or code may not be entirely accurate. I’ve made every effort to review everything, but there might have been some errors that I overlooked. If you discover any issues that require correction, please create an issue on GitHub.

Available Tools

12 tools
create_journal_entryC

Create a journal entry for a specific date. Provide the date in YYYY-MM-DD format along with optional name and content fields.

ParametersJSON Schema
NameRequiredDescriptionDefault
date_onYes
nameYes
contentYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only says 'Create', implying a write operation. No details on side effects, permissions, idempotency, or what happens if the date already exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the core action and key parameter format. It is concise but contains an error that reduces its value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description does not mention output, though an output schema exists. It lacks context on duplicate handling or constraints, leaving the agent underinformed for a creation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description contradicts the input schema by calling 'name' and 'content' optional, while the schema lists them as required. It adds the date format as helpful information but otherwise misleads.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Create', the resource 'journal entry', and the constraint 'for a specific date', which distinguishes it from sibling tools like create_note or create_task.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description only explains what it does, not when it is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_noteA

Create a note in LunaTask. Accepts notebook_id, optional name/content, an ISO date_on, and optional source/source_id metadata for duplicate detection. Returns note_id or duplicate status.

ParametersJSON Schema
NameRequiredDescriptionDefault
notebook_idNo
nameNo
contentNo
date_onNo
sourceNo
source_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behavioral traits: duplicate detection via source/source_id and the return value (note_id or duplicate status). Without annotations, this adds necessary context, though it omits details about error handling or side effects when a duplicate is detected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is just two sentences, with the purpose front-loaded and no extraneous words. Every sentence earns its place by conveying essential information about parameters and return value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the six optional parameters and the presence of an output schema, the description provides a fair overview. However, it lacks explicit indication of required fields (notebook_id is implied but not enforced) and does not cover error scenarios or behavior when required parameters are missing. More detail on return value structure would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining the purpose of notebook_id, name, content, date_on (ISO format), and source/source_id for duplicate detection. This adds significant meaning beyond the raw schema, although it does not elaborate on constraints (e.g., whether notebook_id is actually required).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Create a note in LunaTask' and lists the parameters it accepts, clearly distinguishing it from sibling tools like create_journal_entry or create_task. The verb 'Create' and resource 'note' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 compared to alternatives, such as update_note or delete_note. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_personA

Create a person/contact in LunaTask. Requires first_name and last_name. Optional relationship_strength (family, intimate-friends, close-friends, casual-friends, acquaintances, business-contacts, almost-strangers), source/source_id for duplicate detection, email, birthday (YYYY-MM-DD), and phone. Returns person_id or duplicate status.

ParametersJSON Schema
NameRequiredDescriptionDefault
first_nameYes
last_nameYes
relationship_strengthNo
sourceNo
source_idNo
emailNo
birthdayNo
phoneNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries full burden. It mentions duplicate detection (returns person_id or duplicate status) and lists all parameters. However, it does not disclose potential side effects or limits, which is acceptable for a simple create operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with no extraneous information. It front-loads the purpose and required fields, then lists optional parameters efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 parameters, output schema exists), the description covers all essential aspects: required and optional fields, format hints, and duplicate detection behavior. It is complete for an agent to use effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides enumerated values for relationship_strength, a date format for birthday, and clarifies the purpose of source/source_id for duplicate detection. This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it creates a person/contact in LunaTask, with a specific verb and resource. The sibling tools target different entities (journal entries, notes, tasks, etc.), so this tool is distinctly identifiable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates required fields (first_name, last_name) and explains optional fields like source/source_id for duplicate detection. While it doesn't explicitly state when not to use this tool, the context of sibling tools makes the usage clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_person_timeline_noteA

Create a timeline note for a person in LunaTask. Requires person_id and content. Optional date_on (YYYY-MM-DD) to associate the note with a specific day.

ParametersJSON Schema
NameRequiredDescriptionDefault
person_idYes
contentYes
date_onNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry full behavioral disclosure. It only states that the tool creates a note (mutation) and lists parameters, but omits details on side effects, permissions, rate limits, error handling, or whether the note is appended or replaces existing data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences efficiently deliver the core purpose, requirements, and optional parameter format. No wasted words; front-loaded with the action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with 3 parameters and an existing output schema. The description covers required and optional inputs and the date format. However, it lacks constraints (e.g., person_id must exist) and error handling details, though these are minor given the simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description adds crucial meaning: it clarifies 'person_id' and 'content' as required, and 'date_on' as optional with a specific format (YYYY-MM-DD). This goes beyond the schema's minimal type/title information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a timeline note for a person in LunaTask, with specific verb 'create' and resource 'timeline note for a person'. It distinguishes itself from sibling tools like 'create_note' and 'create_journal_entry' by specifying the person-scoped timeline context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for attaching notes to a person on a timeline, but it does not explicitly compare to alternatives (e.g., 'create_note' for general notes) or state when not to use it. Only required and optional parameters are mentioned, lacking guidance on scenario-based selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_taskC

Create a new task in LunaTask.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
noteNo
area_idNo
statusNolater
priorityNo
motivationNounknown
eisenhowerNo
estimateNo
progressNo
goal_idNo
scheduled_onNo
sourceNo
source_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavioral traits, but it only states a basic create action without mentioning side effects, permissions, or reversibility.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (one sentence) and front-loaded, but it is overly minimal, missing essential detail while avoiding verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 13 parameters and the presence of an output schema, the description is severely incomplete, providing no information about fields, constraints, or return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no meaning to any of the 13 parameters, leaving the agent to rely solely on the schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Create a new task in LunaTask' uses a specific verb and resource, clearly distinguishing the tool from siblings like 'create_note' or 'create_person'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor are any prerequisites or exclusions mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_noteA

Delete a note in LunaTask by note_id. Requires note_id (UUID). Returns success status with note_id and deleted_at timestamp. Note: deletion is not idempotent - second delete will return not found error.

ParametersJSON Schema
NameRequiredDescriptionDefault
note_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description covers key behavioral traits: non-idempotent deletion, response includes status, note_id, and deleted_at, and error on second call. Missing authorization details, but adequate for a simple delete operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (two sentences), front-loaded with the main action, and every sentence adds necessary context without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a delete tool with one parameter and an output schema (not shown but mentioned), the description fully covers purpose, input requirement, response format, and edge case (non-idempotence). No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds value over the schema by specifying the note_id format (UUID) and its role, despite 0% schema coverage. The single parameter purpose is clearly explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Delete' and the resource 'note in LunaTask', distinguishing it from sibling tools like delete_person and delete_task. It specifies the required parameter note_id and the action performed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when deleting a note with a known note_id, but does not explicitly contrast with alternatives like deleting a person or task. However, the unique resource name 'note' makes the context clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_personA

Delete a person/contact in LunaTask by person_id. Requires person_id. Returns success status with person_id and deleted_at timestamp. Note: deletion is not idempotent - second delete will return not found error.

ParametersJSON Schema
NameRequiredDescriptionDefault
person_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that deletion is not idempotent and second attempts return an error, and describes the return structure (success status, person_id, deleted_at). However, no annotations exist, and the description does not cover side effects, permissions, or cascading behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences that front-load the action and resource, followed by return info and a crucial behavioral note. No redundant or irrelevant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the essential aspects for a simple deletion tool: purpose, required parameter, return structure, and idempotency behavior. However, lacks mention of prerequisites, error states for first delete, or any relationship to other entities (e.g., timeline notes). The existence of an output schema reduces the need to detail return values, but the description still adds useful context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With input schema parameter descriptions at 0%, the description provides minimal extra meaning beyond the schema. It only reiterates that person_id is required, which is already indicated by the schema's required array. Does not explain the format, source, or any constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly identifies the action ('Delete a person/contact') and the resource ('in LunaTask'), and specifies the identifier ('by person_id'). Differentiates from sibling delete tools (delete_note, delete_task) by naming 'person/contact'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States that person_id is required and notes non-idempotence, but does not provide explicit guidance on when to use this tool vs. other deletion tools or when not to use it. No mention of prerequisites or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_taskB

Delete an existing task in LunaTask.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden. It states the tool deletes a task but offers no details on irreversibility, side effects, permissions, or return value, which is insufficient for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no redundancy. However, it could be expanded slightly to include key behavioral or parameter details without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple delete tool, the description is incomplete. It omits information about the output schema (which exists), any side effects, and provides no context beyond the basic action.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single required parameter 'id' is not explained beyond its schema definition. With 0% schema description coverage, the description should clarify what 'id' represents (e.g., task ID) but fails to do so.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (delete), resource (task), and system (LunaTask), distinguishing it from sibling tools like create_task and update_task.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for deleting a task but provides no explicit guidance on when to use this tool versus alternatives or any prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pingA

Ping health-check tool that returns a static 'pong' response.

This tool serves as a basic health-check endpoint to verify that the MCP server is functioning correctly.

Args: ctx: The execution context providing access to logging and other MCP capabilities.

Returns: str: The 'pong' response text.

Raises: asyncio.CancelledError: If the operation is cancelled during execution.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses the tool's behavior: it returns a static 'pong' string and may raise asyncio.CancelledError. The behavior is simple and completely transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (Args, Returns, Raises) and is front-loaded with the purpose. It is concise but could be slightly more streamlined by omitting the implementation detail of 'ctx'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple health-check tool, the description is complete: it explains the function, return value, and possible error. An output schema exists but is not needed as the return type is already stated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters and schema description coverage is 100%, so the description adds no required parameter details. The mention of 'ctx' in Args is extraneous but not harmful. Baseline score for zero parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a health-check tool that returns a static 'pong' response, distinguishing it from sibling tools that handle CRUD operations on notes, tasks, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains it serves as a basic health-check endpoint to verify server functionality, providing clear context for when to use it. No explicit alternatives or exclusions are needed given its simplicity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

track_habitC

Track an activity for a specific habit on a given date

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
dateYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as idempotency, whether tracking overwrites or appends, or any side effects. The existence of an output schema is not leveraged for transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise, but it is too brief to cover necessary details. It does not fully earn its place as it sacrifices completeness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and parameter descriptions, the tool definition is incomplete. An agent would be uncertain about how to use the 'id' and 'date' parameters correctly, despite the simple nature of tracking.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It only mentions 'activity for a specific habit', but does not explain that 'id' is the habit identifier or specify the expected date format, leaving ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the action 'Track' and the resource 'activity for a specific habit', which is distinct from the sibling CRUD tools. However, 'an activity' is vague; it does not clarify what constitutes an activity (e.g., completion, count).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, nor any prerequisites (e.g., the habit must already exist). The sibling tools are unrelated, but the description omits context entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_noteA

Update an existing note in LunaTask. Requires note_id (UUID). Optional fields: name, content (replaces entire content due to E2E encryption), notebook_id (to move note), date_on (YYYY-MM-DD). At least one field must be provided. Returns updated note data.

ParametersJSON Schema
NameRequiredDescriptionDefault
note_idYes
nameNo
contentNo
notebook_idNo
date_onNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must cover behavioral traits. It discloses that content replacement is due to E2E encryption, that at least one field must be provided, and that the tool returns updated note data. It could mention if updates are partial or full, but it does state 'replaces entire content' for content. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, very concise. The first sentence establishes purpose and platform, the second lists parameters and constraints. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters (1 required, 4 optional) and an output schema exists, the description covers all needed context: required ID, optional fields with explanations, format constraints, and minimum requirement. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, so the description fully compensates. It explains note_id as UUID, name, content with encryption note, notebook_id with purpose (move note), and date_on with format (YYYY-MM-DD). It also adds the constraint that at least one field is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update an existing note'), the resource ('note'), and the context ('in LunaTask'). It distinguishes from sibling tools like create_note or delete_note by specifying 'update' and requiring an existing note_id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives usage prerequisites: requires note_id and at least one optional field. It lists optional fields with a brief purpose. However, it does not explicitly state when not to use this tool or suggest alternatives (e.g., use create_note if note doesn't exist), but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_taskC

Update an existing task in LunaTask.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
nameNo
noteNo
area_idNo
statusNo
priorityNo
scheduled_onNo
motivationNo
eisenhowerNo
estimateNo
progressNo
goal_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It only states 'Update', offering no details on permissions, side effects, or what fields are updatable. The behavior beyond the action is opaque.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (one sentence) and front-loaded, but it lacks substantive content beyond the verb and resource. While not verbose, it fails to provide enough information to be useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of 12 parameters and no annotations, the description is far from complete. It does not explain the update process, return values, or any behavioral nuances, leaving significant gaps despite the presence of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds no meaning to the 12 parameters. The agent must rely solely on parameter names, which may be ambiguous. No hints are given about valid values or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (update) and the resource (existing task in LunaTask), using a specific verb+resource combination. It distinguishes from sibling tools like create_task and delete_task by specifying 'update existing'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives like create_task or delete_task. No mention of prerequisites or context, leaving the agent to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 12 tool updatesv0.2.1
    • First observedcreate_journal_entry
    • First observedcreate_note
    • First observedcreate_person
    • First observedcreate_person_timeline_note
    • First observedcreate_task
    • First observeddelete_note
    • First observeddelete_person
    • First observeddelete_task
    • First observedping
    • First observedtrack_habit
    • First observedupdate_note
    • First observedupdate_task

TDQS

A3.5/5.0
Disambiguation5/5

Each tool has a distinct purpose targeting a specific entity or action (e.g., create, delete, update). There is no overlap in functionality, and descriptions clearly separate the operations for notes, persons, tasks, journal entries, and habits.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_note, delete_person, update_task). The naming is uniform and predictable across the entire set.

Tool Count5/5

With 12 tools, the count is well within the optimal 3-15 range. Each tool addresses a specific operation, and the scope feels appropriate for a personal task/note/habit manager.

Completeness2/5

The tool set lacks read/list operations for all entities (notes, persons, tasks, journal, habits). Update is missing for persons and journal entries, and delete is missing for journal entries and habits. These gaps will hinder agents that need to retrieve or modify existing data.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tensorfreitas/lunatask-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server