unntak-mcp 0.1.0

mcp server for the unntak.no agent api

unntak-mcp

mcp server for the unntak.no agent api. lets any mcp client (claude code, claude desktop, cursor, ...) read, create and work on unntak tasks with an agent token.

the server runs locally over stdio. the token stays in the local environment and is only sent to unntak.no (or the explicitly configured UNNTAK_URL).

setup

1. in unntak.no, open :) → settings → agents and create a token. the token is scoped to a tag path (like agent;007), so the agent only ever sees tasks under those tags.
2. add the server to your client:

claude mcp add unntak --env UNNTAK_TOKEN=unntak-agent-... -- uvx unntak-mcp

for a local unntak instance, add --env UNNTAK_URL=http://localhost:8000.

the token is a password. never commit it, paste it into issues, or include it in logs. revoke it in unntak settings if it is exposed.

connection check

check the production api and token before configuring an mcp client:

UNNTAK_TOKEN=unntak-agent-... uvx unntak-mcp --check

a successful check prints the agent name, scope, and open task count without changing any tasks.

agent flow

the server sends these rules to the model automatically on connect: check list_tasks at session start (scheduled tasks appear when due), read a task's comments before working on it, start_task before working (409 = someone else has the timer, take another task), comment progress along the way, and always complete_task or stop_task before ending a session so no timer is left running.

tools

• list_tasks — open tasks in the agent's scope
• get_task — one task with comments
• add_task — create a task (scope tags are always prepended)
• start_task / stop_task — run the focus timer; the owner sees it live
• log_time — log a block of seconds without the live timer
• comment — comment on a task under the agent's name
• complete_task — finish a task and archive it

skill (no mcp needed)

skill/SKILL.md is an agent skill for clients that read skills instead of running mcp servers (like claude code project skills). copy it into a project's .claude/skills/unntak/ and set UNNTAK_TOKEN in the environment; the agent then works the same flow over plain http.

development

uv sync --dev
uv run pytest
uv build --no-sources

test the built wheel rather than the editable source:

UNNTAK_TOKEN=unntak-agent-... \
  uvx --from ./dist/unntak_mcp-0.1.0-py3-none-any.whl unntak-mcp --check

release

the repository includes CI for Python 3.11 and 3.14. it builds and smoke-tests both distribution formats on every pull request and push to main.

for publishing, create a pypi environment in the github repository and add L0JK/unntak-mcp with workflow publish.yml as a trusted publisher in the pypi project settings. no pypi token is stored in github.

make sure the package version is final, then create a matching tag:

uv run pytest
uv build --no-sources
git tag -a v0.1.0 -m v0.1.0
git push origin v0.1.0

the tag starts the publish workflow. it refuses to publish if the tag and package versions differ.

after the pypi package is available, publish server.json separately to the official mcp registry. the registry stores discovery metadata; pypi stores the installable package.