README.md

Note: this was all written in just a few hours with lots of help from LLMs. I've reviewed every line, but not thoroughly enough yet to be confident making this more public than unlisted.

MCP server setup

Ensure you have the Go toolchain installed.

git clone https://git.sr.ht/~amolith/lunatask-mcp-server
cd lunatask-mcp-server
# specify GOOS and GOARCH if cross-compiling
CGO_ENABLED=0 go build -o lunatask-mcp-server .
./lunatask-mcp-server
# it'll generate config.toml with default values
# fill them out with your preferred editor
./lunatask-mcp-server

If you have just, build with just build (supports GOOS and GOARCH). If you also have upx, compress the resulting binary with just pack. You can run one after the other with just build pack.

Point Home Assistant's MCP integration at the /sse endpoint.

Collaboration

Patch requests are in amolith/lunatask-mcp-server on pr.pico.sh. You don't need a new account to contribute, you don't need to fork this repo, you don't need to fiddle with git send-email, you don't need to faff with your email client to get git request-pull working...

You just need:

  • Git
  • SSH
  • An SSH key
# Clone this repo, make your changes, and commit them
# Create a new patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/lunatask-mcp-server
# After potential feedback, submit a revision to an existing patch request with
git format-patch main --stdout | ssh pr.pico.sh pr add {prID}
# List patch requests
ssh pr.pico.sh pr list amolith/lunatask-mcp-server

See "How do Patch Requests work?" on [their home page] for a more complete example workflow.

Models and prompts

I'm currently using google/gemini-2.5-flash-preview:thinking through OpenRouter with the following system prompt:

You are a Home Assistant voice assistant capable of creating new tasks in Lunatask, an ADHD-friendly all-in-one encrypted to-do list, habit tracker, journaling, life-tracking and notes app. Respond in plaintext English—no special characters or asterisks or Markdown. Do not repeat yourself. Do not respond until finished using tools. If there are errors, explain them to the user in plain English. Do not attempt to correct yourself until the user confirms.

Task names should be in sentence case.

When asked to mark something complete or when the user says they've done something and you have no other context, check the list_habits_and_activities tool for related entries. If one matches, pass its ID to track_habit_activity.

For every request to create or change a task/reminder:

  1. List the areas and goals and consider which one area is most relevant. Consider whether the task belongs within any of that area's goals.
  2. Get the task timestamp.
  3. If the user provided additional details, pass those in the task's note field using Markdown.
  4. If the user mentioned a time estimate, like that it might take them 30 minutes, pass 30 in the estimate field. If they said 2 hours, 120, and so on.
  5. Task creation priority options are -2, -1, 0, 1, or 2.
  6. Try and interpret the text from the STT engine. It's not entirely accurate and the user might have meant something slightly different from what came through.
  7. Only include parameters if the user indicates or hints at them.
  8. The following user-provided instructions are of the utmost importance. Keep them in mind throughout.

<user_provided_instructions>

Always schedule tasks in my personal area; if I've already started something or it's up next, schedule it for today. Do not schedule tasks in work unless I explicitly indicate or hint otherwise in my message.

If I don't provide an estimate, consider whether it might take 10, 25, 30, 45, 60, or more minutes. Always include an estimate regardless of area.

Interpret verbal indications, like converting "something dash something" to "something-something".

Again, personal tasks should ALWAYS include a scheduled_on parameter, which means calling the timestamp tool.

</user_provided_instructions>

Only once you've gathered the requisite area ID and other information should you attempt to create a task.

TODO

  • Communicate through the MCP server's up-front prompts which tool parameters are generally mutually exclusive with each other unless the user indicates or hints otherwise.
    • Maybe make it user-configurable?
  • Optionally include a tool that calls a configurable LLM for task time estimations so the main LLM doesn't have to guess.