Connect an agent to Timerrr with MCP

The Timerrr MCP bridge lets a compatible local MCP host record client work, track separate actors, attach evidence, and prepare human time for review. It uses a revocable account token and the official Python MCP SDK over stdio.

1. Create a scoped token

Sign in and open Agent work → Connections. Create a token with Read work, Record work, and Draft time permissions. Save it when it appears. Tokens expire after ninety days and can be revoked in the same panel. An active trial or subscription is required.

2. Install the local bridge

From your local Timerrr source checkout, install the optional MCP requirements into a Python environment:

python -m venv .venv
.venv/bin/pip install -r requirements-mcp.txt

Use Python 3.11 or newer. The bridge does not need a local database or Flask server; it connects to the URL you configure.

3. Configure your MCP host

For hosts that accept the common mcpServers configuration, use absolute paths and your own token. Select a host that supports stdio servers. Keep this configuration private.

{
  "mcpServers": {
    "timerrr": {
      "command": "/absolute/path/timerrr/.venv/bin/python",
      "args": ["/absolute/path/timerrr/mcp_server.py"],
      "env": {
        "TIMERRR_URL": "https://timerrr.app",
        "TIMERRR_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

For a local app, use http://127.0.0.1:5001. HTTPS is required for other hosts. This release uses a local stdio bridge, not a hosted OAuth MCP endpoint. The pinned SDK targets the 2025-11-25 protocol for compatibility.

4. Try a recorded session

Ask your agent: “List my clients. Start Acme’s checkout fix with a twenty-minute agent budget. Track your execution under your own actor ID, attach the result, and finish the session. Do not infer my human effort.”

The tools are list_clients, get_active_work, get_work, start_work, record_work_event, finish_work, draft_timesheet, and get_draft. Every mutation requires a unique request_id. Reuse that exact ID and arguments when retrying an uncertain response.

For delegation, start a human session in the website and give its session ID to your agent. It can join with actor_started, actor_kind agent, and a distinct actor_id. Agents should heartbeat every thirty seconds and stop if continue_work is false. Record waiting under a separate waiting actor and stop the active actor when transitioning.

Enforce a command’s time budget

The optional POSIX runner stops a subprocess and its process group at its elapsed cutoff, renews leases in the background, and records its result. Set TIMERRR_URL and TIMERRR_TOKEN in your environment, then run from the source checkout:

.venv/bin/python -m agent_tools.runner \
  --client-id 1 --title "Checkout fix" --budget 1200 \
  -- python your_agent_task.py

Use --work-id 42 to join an existing session; the runner then stops only its own actor. Use --artifact https://example.com/pull/42 to attach an output reference. The child process does not receive TIMERRR_TOKEN. Commands that deliberately detach from the process group need enforcement in their own execution environment.

A live card inside the conversation

In hosts supporting MCP Apps, get_work and get_active_work expose an interactive card with separate totals, remaining budget, receipt notes, and a Finish session control. Other hosts receive the same accounting as structured data and text. Host support for the UI extension varies.

Review before export

Ask for a draft with explicit ISO timestamps and timezone offsets. Open Agent work → Human review to adjust and approve the proposed human intervals. Approval is only available in the website. Then generate the client CSV in Timesheets.

Timerrr does not import your issue tracker or infer hours from commits. Agents can attach links from tools you already use. Read the accounting and uncertainty rules.

Protocol references: Python MCP SDK v1.26.0 · MCP Apps.