# Tallymeter

> Tallymeter is a time tracker and invoicer for people and teams that bill for their time. AI agents can use it two ways: a token-authenticated REST API at /api/v1 (timer start/stop/status, entry updates, projects, feedback) and a native MCP server at /mcp (Streamable HTTP) that additionally logs completed work and reports unbilled time. Tracked time can later be turned into client-ready PDF invoices in the web app, and a two-way Jira Cloud sync keeps tracker time and Jira worklogs reconciled ticket by ticket.

Authentication: HTTP Bearer with a personal access token (both REST and MCP). A signed-in user creates tokens at Settings → API tokens (https://tallymeter.com/settings). Tokens are scoped — `timer` (start/stop/read the timer), `projects:read` (list projects), `entries:write` (log and update time entries), `reports:read` (unbilled totals). Requests without a valid token get JSON 401; tokens missing the required scope get 403.

All timestamps are ISO-8601 UTC. Errors are JSON with a `message` field (and `errors` per field for validation failures). Rate limit: 120 requests/minute per user. Stopping when no timer runs is a success (`{"running": false, "stopped": null}`), so retries are safe. Every entry records its `source` (web/api/mcp) and `agent` (the token's name) — give each agent its own named token and a fleet's work stays attributable per agent.

Quick examples:

    # Read timer state
    curl -H "Authorization: Bearer $TOKEN" https://tallymeter.com/api/v1/timer

    # Start a timer (project_id optional; starting stops any running timer first)
    curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d '{"description": "ABC-1 fix login", "project_id": 1}' \
      https://tallymeter.com/api/v1/timer/start

    # Stop the running timer (idempotent)
    curl -X POST -H "Authorization: Bearer $TOKEN" https://tallymeter.com/api/v1/timer/stop

    # Fix an entry's description in place — running or finished (entries:write scope)
    curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d '{"description": "ABC-1 fix login"}' \
      https://tallymeter.com/api/v1/entries/42

    # Tracked vs unbilled totals for one ticket (reports:read scope)
    curl -H "Authorization: Bearer $TOKEN" https://tallymeter.com/api/v1/tickets/ABC-1/summary

    # Who does this token belong to? (any scope)
    curl -H "Authorization: Bearer $TOKEN" https://tallymeter.com/api/v1/me

    # File feedback for the developers (any token scope; category: bug|missing-capability|docs|other)
    curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d '{"message": "I looked for a way to edit an entry but found no endpoint.", "category": "missing-capability"}' \
      https://tallymeter.com/api/v1/feedback

## Plans & access

Every account starts with a free 30-day trial — no card required, full product including API and MCP access. After the trial a paid subscription is required (€9/month or €90/year); API/MCP access is included in every plan (it is not a separate tier or add-on). When a plan lapses, tokens keep authenticating but every call returns JSON 403 with a renewal link — data is never deleted. Humans sign up at https://tallymeter.com/register and manage the subscription at https://tallymeter.com/billing; tokens are created at https://tallymeter.com/settings.

## MCP server

Connect any MCP client (Claude Code, Claude Desktop, Cursor, ...) to https://tallymeter.com/mcp (Streamable HTTP) with the same Bearer token:

    claude mcp add --transport http tallymeter https://tallymeter.com/mcp --header "Authorization: Bearer $TOKEN"

Tools: timer-status, start-timer, stop-timer (idempotent), list-projects, log-time (file a finished piece of work after the fact — description plus either duration_minutes or started_at/ended_at), update-entry (rewrite a running or finished entry's description/project in place — no need to restart the timer; billed entries are frozen), unbilled-summary (finished, not-yet-invoiced time with per-task totals), send-feedback (tell the developers about a missing capability, bug or unclear docs — works with any scope). Give every entry a meaningful description (e.g. ticket key + what was done) — undescribed time is never billed.

Agent Skill: a ready-made open-source skill (MIT) teaches Claude Code and compatible harnesses this whole track→log→bill workflow, MCP-first with REST fallback. Install: `git clone https://github.com/mkantautas/tallymeter-skill ~/.claude/skills/tallymeter` — source and README at https://github.com/mkantautas/tallymeter-skill.

## API

- [OpenAPI specification](https://tallymeter.com/openapi.json): machine-readable spec of every endpoint, schema and error shape
- [API documentation](https://tallymeter.com/docs/api): human-readable guide with curl examples

## Product

- [Changelog](https://tallymeter.com/changelog): what shipped, when
- [Jira sync](https://tallymeter.com/jira): two-way, create-only worklog sync with Jira Cloud
- [Try it](https://tallymeter.com/try): guest mode, no account needed