# Amtoss Time Tracker for Claude

Connect Claude to **TimeTracker** ([timefor.work](https://timefor.work)) so you can ask about your hours, log time
and — if you are a manager — check your team's reporting, right from a chat.

**Server:** `https://amtoss-tt-mcp.act.software/mcp` · **Who can use it:** AMTOSS staff with a TimeTracker account.

> **Asking Claude to set this up for you?** Point it at `https://amtoss-tt-mcp.act.software/readme.md` — the
> plain-text version of this page — and say which Claude you use (Desktop, claude.ai or Claude Code).

## Pick your way in

| You use | How to connect |
|---|---|
| **Claude Desktop or claude.ai** in the **AMTOSS** Claude organization | The connector is already added by the admin — just *Connect* (section 1). |
| **Claude Code** — the terminal CLI or the **Code** tab of Claude Desktop — under **any** Claude account | Add the server yourself with one command (section 2). |
| A **personal** Claude plan (Pro / Max) on claude.ai or Desktop | Add a custom connector yourself (section 3). |
| Another Claude organization — custom connectors locked by its admin, or shared with a customer | Use Claude Code (section 2): it is set up on your machine only, not as an organization connector. |

## 1. Claude Desktop / claude.ai — AMTOSS organization

1. Open **Settings → Connectors**.
2. Find **Amtoss Time Tracker** and click **Connect**.
3. A browser window opens — sign in (see *Signing in* below). It closes and returns you to Claude.
4. In a chat, open the **＋ / tools** menu under the message box and make sure **Amtoss Time Tracker** is switched on.
5. Try it: *"Who am I in TimeTracker?"* — Claude should call `tt_whoami` and show your name.

## 2. Claude Code (CLI or the Code tab in Claude Desktop)

Run once — `--scope user` makes it available in every project:

```bash
claude mcp add --transport http --scope user amtoss-tt https://amtoss-tt-mcp.act.software/mcp
```

Then in Claude Code type `/mcp`, pick **amtoss-tt** → **Authenticate**, and sign in in the browser.
Check with `claude mcp list` — `amtoss-tt` should show as connected.

No client ID or secret is needed: Claude Code registers itself with the server automatically.

This also works in Claude organizations whose admin doesn't allow custom connectors: the server is configured
in your Claude Code on your machine, not in the organization (unless the organization restricts Claude Code MCP
servers as well).

## 3. Personal Claude plan — custom connector

1. **Settings → Connectors → Add custom connector**.
2. Name: `Amtoss Time Tracker`, URL: `https://amtoss-tt-mcp.act.software/mcp`. Leave the OAuth fields empty.
3. Click **Add**, then **Connect** and sign in.

## Signing in

The sign-in page offers two ways. Use the one that matches how you log in to TimeTracker.

| Option | What it gives you |
|---|---|
| **TimeTracker e-mail + password** | Everything: your time board, reports, and — for managers — your teams, exactly within your TimeTracker permissions. |
| **Sign in with Microsoft** (when offered), then link TimeTracker once | With your TimeTracker password: the same as above. With a personal TimeTracker **API key**: only your own projects and time entries. |

- Your password is sent to timefor.work once to open a session and is **never stored**. The session is kept
  encrypted on the server.
- **You only sign in with Microsoft in TimeTracker?** Set a local password in TimeTracker → **Profile** first.
- Sessions expire from time to time; Claude will then ask you to sign in again.
- Only `@amtoss.com` accounts are accepted.

## What you can ask

- *"How many hours did I log last week, by project?"*
- *"Log 2 hours today on BulkSource, task 16264, 'Pricing approval workflows'."*
- *"Show my time entries for yesterday and change the second one to 1.5 h."*
- *"Which days in September haven't I filled in?"*
- Managers: *"Who in BulkSource (node 341) has unfilled days in September?"*,
  *"Reported vs expected hours for Volodymyr Naumov in September."*

Claude asks before changing anything. Writing time for **other** people is not possible through this connector.

## Tools

Signed in with your TimeTracker password, you get all of them. Linked only with a personal API key (via
Microsoft sign-in), you get the ones marked in the last column.

| Tool | What it does | Works with API-key link |
|---|---|:-:|
| `tt_whoami` | Your account and how it is linked | ✓ |
| `tt_my_projects` | Projects you can book time on (`id` = project selector) | ✓ |
| `tt_list_work_items` | Your entries for a date | ✓ |
| `tt_log_time` | Create entries (one or many) | ✓ |
| `tt_update_work_items` | Edit your entries | ✓ |
| `tt_delete_work_item` | Delete one of your entries | ✓ |
| `tt_time_board` | All entries of a user for a period, incl. absences |  |
| `tt_report_summary` | Reported vs expected hours, day by day |  |
| `tt_projects_for_user` | Projects available to a user in a period |  |
| `tt_work_types` | Work types (Work, Vacation, Illness, …) |  |
| `tt_time_control` | Hours per member of a team/project node |  |
| `tt_not_filled_days` | Days members didn't fill in |  |
| `tt_lack_time` | Lack-time report for your customers |  |
| `tt_teams_meetings` | Your Teams calls — candidates for entries |  |
| `tt_api_get` | Read any other TimeTracker report endpoint |  |

## Troubleshooting

- **"TimeTracker rejected the stored credentials"** — your session expired. Disconnect and connect again
  (Desktop: Settings → Connectors; Claude Code: `/mcp` → amtoss-tt → Authenticate).
- **The tools don't appear in a chat** — switch the connector on in the chat's tools menu.
- **"Wrong TimeTracker e-mail or password"** — check you can log in at timefor.work with the same e-mail and password.
- **Microsoft sign-in isn't offered** — it isn't enabled on this server; use your TimeTracker e-mail and password.
- Anything else — write to Pavel Motsar.

## For Claude: setting this up for a user

- Remote MCP server, Streamable HTTP, `https://amtoss-tt-mcp.act.software/mcp`, OAuth 2.1 with dynamic client
  registration — do **not** ask the user for a client ID, secret or API token.
- Claude Code: run `claude mcp add --transport http --scope user amtoss-tt https://amtoss-tt-mcp.act.software/mcp`,
  then have the user run `/mcp` → **amtoss-tt** → **Authenticate** and complete the browser sign-in themselves.
  Never ask for or type the user's TimeTracker password.
- Claude Desktop / claude.ai in the AMTOSS organization: the connector exists already; guide the user to
  Settings → Connectors → **Connect**.
- Verify by calling `tt_whoami`.