![\"Timo](\"https://unpkg.com/@anish23_05/timo-mcp@latest/assets/timo-mascot.png\")
\n\n \n
\n Detailed read-only MCP tools for Timo workspace operations, device health, time summaries, and audit context.\n
\n\n---\n\nTimo MCP runs locally over stdio and talks only to the Timo API using a scoped API token.\n\nIt does not connect to the VM, Postgres, dashboard cookies, Lark write APIs, screenshots, or raw activity samples.\n\n## Install\n\nCreate an API token in Timo:\n\n1. Open Timo Dashboard.\n2. Go to **Integrations**.\n3. Create an API token with the read-only scopes you want.\n4. Copy the token once and keep it private.\n\nAdd this to your MCP client config:\n\n```json\n{\n \"mcpServers\": {\n \"timo\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@anish23_05/timo-mcp@latest\"],\n \"env\": {\n \"TIMO_API_BASE\": \"https://timo.emiactech.com\",\n \"TIMO_API_TOKEN\": \"timo_mcp_atk_...\"\n }\n }\n }\n}\n```\n\nRestart the MCP client after editing the config.\n\n## Tools\n\n- `timo_mcp_capabilities` — explains tools, scopes, limits, date formats, and privacy boundaries.\n- `timo_workspace_overview` — workspace totals for people, teams, devices, versions, today time, manual-time requests, and open activity flags.\n- `timo_people_list` — active people with role, team, managed team, shift, and device summary.\n- `timo_user_detail` — one user's profile, device health, time totals, and recent manual-time requests.\n- `timo_device_health` — app version, platform, runtime state, heartbeat freshness, and permission health.\n- `timo_version_adoption` — version/platform/state adoption buckets and unknown/stale users.\n- `timo_running_users` — users currently RUNNING with a fresh heartbeat.\n- `timo_team_summary` — team managers, roster, device counts, permission issues, and time totals.\n- `timo_break_summary` — inferred break time by user/day with source-of-truth gap evidence; lunch is separated as the longest qualifying candidate when a long break overlaps the local lunch window.\n- `timo_time_summary` — per-user/per-day tracked, meeting, manual, invalidated, and total time.\n- `timo_manual_time_requests` — manual-time request and decision audit metadata.\n- `timo_activity_flags_summary` — privacy-safe flag counts and recent flag summaries.\n\n## Scopes\n\n- `read:people` — people, roles, teams, shifts, roster context.\n- `read:device-health` — desktop platform, version, runtime state, heartbeat, permissions.\n- `read:time-summary` — aggregated time summaries and privacy-safe activity flag summaries.\n- `read:manual-time` — manual-time requests and approval audit metadata.\n\nSome detailed tools require multiple scopes. If a token is missing a scope, the tool fails clearly with `insufficient_scope` instead of returning partial or guessed data.\n\n## Example Questions\n\n- \"Which Timo version is everyone using?\"\n- \"Who is currently running Timo?\"\n- \"Show me users with stale or missing desktop heartbeats.\"\n- \"Which Mac users are missing Screen Recording or Accessibility?\"\n- \"Summarize today's tracked time by team.\"\n- \"Kal kisne kitna break liya?\"\n- \"Yesterday, show lunch candidates separately from other breaks.\"\n- \"For yesterday's breaks, show the actual gaps and any manual-time approval reasons.\"\n- \"Show pending manual-time requests.\"\n- \"Give me privacy-safe activity flag counts for this week.\"\n- \"What can this Timo MCP read, and what is intentionally blocked?\"\n\n## Privacy\n\nThis MCP never exposes:\n\n- screenshots or screenshot URLs\n- S3 keys\n- raw `ActivitySample` rows\n- raw keystroke/click/mouse minute timelines\n- foreground window titles\n- browser URLs\n- dashboard cookies\n- token hashes or secrets\n\nIt also has no write tools. It cannot approve requests, edit time, create users, change settings, or send Lark messages.\n\n## Limits\n\n- List tools return at most 200 rows.\n- Summary-style tools allow at most 31 days per request.\n- Dates use `YYYY-MM-DD`.\n- Timezone accepts IANA names such as `Asia/Kolkata` or `UTC`.\n- Break summaries default to yesterday. Breaks are inferred from gaps between tracked work/meeting/manual blocks; each gap includes previous/next tracked-block evidence. Lunch is the longest qualifying candidate only unless users explicitly label it.\n\n## Security\n\n- Use one token per person or machine.\n- Do not paste tokens into chat or commit them to git.\n- Revoke lost or shared tokens from **Integrations**.\n- Rotate any token that was accidentally shared.\n\n## Local Development\n\n```bash\npnpm --filter @anish23_05/timo-mcp build\nTIMO_API_BASE=http://localhost:4010 TIMO_API_TOKEN=token node apps/mcp/dist/index.cjs\n```\n","readmeFilename":"README.md"}