LunaTask

LunaTask MCP Server provides a lightweight bridge that lets AI tools securely interact with LunaTask data through the MCP protocol. It runs locally as a subprocess, handling task, note, and habit data via a standardized interface while keeping sensitive fields encrypted end-to-end.

How to use

Connect to the LunaTask MCP Server from any MCP-compatible client by starting the server locally with a configuration file that contains your LunaTask API bearer token. Once running, your client can discover available resources, read non-sensitive metadata, and perform write operations such as creating tasks, notes, journal entries, and people. Be mindful that end-to-end encryption hides certain sensitive fields in responses, so you’ll manage those fields during create requests or within the LunaTask app.

How to install

# Install dependencies and set up the local environment (uses uv to manage the server)
uv sync

# Optionally verify that the Python module imports correctly
uv run python -c "import lunatask_mcp"

Additional sections

Configuration and startup require a bearer token for the LunaTask API. Create a TOML configuration file from the example, insert your token, and start the server using the documented command.

Security and privacy are built in: task names, notes, and note content are not exposed in GET responses due to end-to-end encryption. You can include these fields in create requests and LunaTask encrypts them client-side. Bearer tokens are never logged, and the server validates configuration on startup.

To start the MCP server, run the following command with your configuration file path: uv run lunatask-mcp --config-file /path/to/your/config.toml

If you need help with options or want to verify connectivity, you can use the help flag: uv run lunatask-mcp --help

Common startup notes:

• The server uses a local stdio transport; it is intended for single-machine workflows.
• You can also override runtime settings on the command line, such as rate limits and timeouts, when starting the server.

Configuration notes

Configuration is provided via a TOML file and command-line options. The precedence is: command-line arguments > configuration file > defaults. A bearer token is required to authenticate with the LunaTask API.

Example configuration steps show how to copy and edit the configuration file, then start the server with that file.

Notes on usage and behavior

• Task IDs are provided by LunaTask and remain consistent across API calls. Use the All Tasks discovery resource to learn existing IDs.
• Rate limiting is enforced per server instance. If you hit a limit, wait and retry.
• Discovery resources describe available endpoints, filters, and guardrails for list and area/global views.

Important token and URL references

Create and use a LunaTask API bearer token by generating an access token in the LunaTask app under Access tokens, then place that token in your configuration file as lunatask_bearer_token.

Available tools

create_task

Creates a new task, requiring a name and area_id. Optional fields include content, planning data, priority, motivation, Eisenhower value, and source metadata. Returns a success response with the new task_id.

create_note

Creates a new note with optional notebook_id, name, content, date_on, and source metadata to ensure idempotency. Returns a success response with the note_id or a duplicate indication if the API returns 204 No Content for duplicates.

update_note

Updates an existing note by note_id. Allows partial updates to name, content, notebook_id, or date_on. Content may be replaced due to end-to-end encryption. Returns a success response with the updated note payload.

delete_note

Permanently deletes a note by note_id. Returns the deleted note_id and timestamp on success. Deletion is not idempotent.

create_journal_entry

Creates a journal entry for a specific date with optional name and content (Markdown). Returns the journal_entry_id on success; name and content are not returned due to encryption.

create_person

Creates a new person/contact with required first_name and last_name. Optional fields include relationship_strength and contact details. Returns the person_id on success, or a duplicate indication if applicable.

create_person_timeline_note

Creates a timeline note for an existing person with required person_id and content; optional date can be provided. Returns person_timeline_note_id on success.

delete_person

Deletes a person/contact by person_id. Returns the person_id and deletion timestamp on success. Deletion is not idempotent.

update_task

Updates an existing task by ID with the provided fields. Returns the full serialized task payload.

delete_task

Permanently deletes a task by task_id. Deleted tasks cannot be recovered.

track_habit

Logs habit activity for a given habit_id on a specific date and returns a confirmation message.