Time Doctor MCP Server
This server provides read-only Time Doctor MCP tools for inspecting companies, users, projects, tasks, worklogs, and productivity statistics.
List companies/workspaces and get a company by ID.
List users with company, email/name, pagination, limit, and archived-user filters; get a user by ID.
Check whether a company invitation exists for an email address, without sending or managing invitations.
List projects in a company with filters, or get a project by ID.
List tasks in a company by project, name, status, pagination, or limit; get a task by ID.
Retrieve detailed work-session logs for a user/company within a time range, optionally resolving task/project names.
Retrieve aggregated time-use/productivity stats by user/company/time range/category, including application/category time and productive vs. unproductive time.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Time Doctor MCP Server Show productive vs unproductive time for user 42 this week."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Time Doctor MCP Server
MCP server for Time Doctor's employee time-tracking / productivity-monitoring API - companies, users, projects, tasks, and time-use statistics, for AI assistants and the WYRE Conduit gateway.
Authentication
Time Doctor's current, officially documented API (https://timedoctor.redoc.ly, API Version 1.0.0) authenticates with the same email/password a user logs into app.timedoctor.com with - there is no separate client-ID/secret application-registration flow. POST /api/1.0/login exchanges the email/password for a JWT bearer token valid for six months (Authorization: JWT {token} on every subsequent call). This server handles that exchange (and re-login on rejection) internally - callers only ever need to supply the email/password.
Some Time Doctor accounts require a TOTP (2FA) code at login; accounts with 2FA enabled are not currently supported by this connector.
Related MCP server: TrackingTime MCP Server
Configuration
Copy .env.example and set the variables below.
Env var | Required | Description |
| For stdio and | Time Doctor account email address. |
| For stdio and | Time Doctor account password. |
| No |
|
| No |
|
| Yes for HTTP | Service-to-service secret. The HTTP server logs an error and exits non-zero when this is empty or a known placeholder ( |
| No | Set to exactly |
| No | Bind address when a real |
| No | HTTP port. Defaults to |
| No |
|
/health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.
HTTP authentication
With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before vendor credentials are read.
TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
-H "X-TimeDoctor-Email: $TIMEDOCTOR_EMAIL" \
-H "X-TimeDoctor-Password: $TIMEDOCTOR_PASSWORD" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'In AUTH_MODE=gateway, /mcp also requires X-TimeDoctor-Email and X-TimeDoctor-Password. Those headers are the only credential source for that request. AUTH_MODE=env still requires the signed X-Gateway-S2S header, then uses TIMEDOCTOR_EMAIL and TIMEDOCTOR_PASSWORD from the environment.
Request limits
HTTP request bodies are capped at 256 KiB (262144 bytes). After the
X-Gateway-S2Scheck (and, in gateway mode, the credential header check) passes, aContent-Lengthabove the cap returns 413 with a JSON-RPC error; bodies withoutContent-Lengthare capped by the MCP SDK transport. Unauthenticated requests still get 401 first.tools/callarguments are capped at 10,000 elements (every array item and object key at any depth). Larger inputs return anisErrortool result with the fixed message "Tool input exceeds the maximum of 10000 elements" and are never dispatched.
These limits address CVE-2026-111768 / GHSA-46jr-4wx8-v453 (memory exhaustion during validation) and GHSA-f897-62hf-6gxq (no request body / batch cap).
Tools
Companies
timedoctor_list_companies- companies (workspaces) the authenticated user owns or administers.timedoctor_get_company- a single company by ID.
Users
timedoctor_list_users- users, optionally scoped to a company and filtered by email/name.timedoctor_get_user- a single user by ID.timedoctor_check_invitation- whether a company invitation exists for an email address (read-only).
Projects
timedoctor_list_projects- projects in a company.timedoctor_get_project- a single project by ID.
Tasks
timedoctor_list_tasks- tasks in a company, filterable by project, name, or open/closed status.timedoctor_get_task- a single task by ID.
Activity / Stats
timedoctor_get_worklog- detailed work-session log (start time, duration, task/project, mode) for a user or company within a time range.timedoctor_get_timeuse_stats- aggregated productivity statistics (time per application/category, productive vs. unproductive) for a user or company within a time range.
Scope
This is a v1 / MVP surface covering the core MSP time-tracking-oversight workflow: who's tracked where, and how their time breaks down. Explicitly out of scope for now: Files (screencasts/screenshots), Categories, Work Schedules (lower-value admin config), any user invitation/creation/deletion mutation, and the "login as" user-impersonation endpoint (a real security-sensitive feature). They can be added as a follow-up if there's demand.
Development
npm install
npm run build
npm test
npm run lint # tsc --noEmit
# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http
# Local HTTP only, without a service-to-service secret (binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_HTTP_HOST=127.0.0.1 npm run start:httpDocker
The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass a real S2S secret. In gateway mode, Time Doctor credentials arrive on each request as headers; they are not read from the environment.
docker build -t timedoctor-mcp .
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-p 127.0.0.1:8080:8080 \
timedoctor-mcpCompose refuses to start when CONDUIT_S2S_SECRET is unset. The gateway service sets AUTH_MODE=gateway, does not inject TIMEDOCTOR_EMAIL or TIMEDOCTOR_PASSWORD, and publishes 127.0.0.1:8080:8080:
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose upSingle-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses TIMEDOCTOR_EMAIL and TIMEDOCTOR_PASSWORD. It is separate from the gateway Compose service above.
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-e AUTH_MODE=env \
-e TIMEDOCTOR_EMAIL=you@example.com \
-e TIMEDOCTOR_PASSWORD=your-password \
-p 127.0.0.1:8080:8080 \
timedoctor-mcpLocal HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning. A non-loopback MCP_HTTP_HOST (including the image default 0.0.0.0) makes startup exit:
MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_ALLOW_INSECURE_DEV=1 npm run start:httpAvailable Tools
11 toolstimedoctor_check_invitationA
Check whether a Time Doctor company invitation exists for an email address (read-only - does not send or manage invitations).
Inputs: email (required), company (required).
timedoctor_get_companyA
Get a single Time Doctor company by ID.
Inputs: companyId (required).
timedoctor_get_projectC
Get a single Time Doctor project by ID.
Inputs: company (required), projectId (required).
timedoctor_get_taskB
Get a single Time Doctor task by ID.
Inputs: taskId (required), company (required).
timedoctor_get_timeuse_statsB
Get aggregated Time Doctor productivity statistics (time spent per application/category, productive vs. unproductive) for a user or company within a time range.
Inputs: company (required), to, from, page, +3 more.
timedoctor_get_userA
Get a single Time Doctor user by ID.
Inputs: userId (required), company.
timedoctor_get_worklogA
Get detailed Time Doctor work-session log (start times, duration, task/project, mode) for a user or company within a time range. For best performance, query <=7-day windows at a time.
Inputs: company (required), to, from, user, +1 more.
timedoctor_list_companiesA
List Time Doctor companies (workspaces) the authenticated user owns or administers.
Inputs: no named parameters.
timedoctor_list_projectsC
List Time Doctor projects in a company.
Inputs: company (required), all, name, page, +1 more.
timedoctor_list_tasksA
List Time Doctor tasks in a company, optionally filtered by project, name, or open/closed status.
Inputs: company (required), name, page, limit, +2 more.
timedoctor_list_usersA
List Time Doctor users, optionally scoped to a company and filtered by email/name.
Inputs: name, page, email, limit, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools are clearly distinct by resource (companies, users, projects, tasks, worklogs, stats). The only mild overlap is between list_projects/list_tasks and get_project/get_task, but the list/get distinction is standard and clear. check_invitation is unique and well-scoped.
All tools follow a consistent timedoctor_verb_noun pattern (list/get/check). The only minor deviation is check_invitation instead of get_invitation or list_invitations, but it is still readable and consistent with the verb-first convention.
11 tools is well within the ideal range for a domain-specific server. Each tool covers a distinct resource or operation, and the count feels appropriate for Time Doctor's API surface without being bloated.
The server covers read operations well across companies, users, projects, tasks, worklogs, and stats, but lacks write operations entirely (no create/update/delete for projects, tasks, or users). For a read-only reporting/analytics server this would be complete, but the presence of check_invitation hints at broader management capabilities that are not fully covered.
Maintenance
Related MCP Connectors
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Connect AI assistants to Talentflake for time, attendance, leave, and expenses.
Time tracking you talk to: log, check and fix your work hours from your AI assistant.
Read your tracked time and projects, pause tracking or add a note, from Claude or ChatGPT.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Clockify time tracking API to manage time entries, projects, tasks, and workspaces through natural language commands.81 npm5ISC
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to the TrackingTime API v4 for managing projects, tasks, and team assignments. Users can start or stop timers, log manual time entries, and organize project workflows using natural language.10 npmMIT

TrackingTime MCPofficial
FlicenseNot gradedqualityBmaintenanceConnects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.-- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with the Toggl time tracking API to manage time entries, projects, and workspaces through natural language.22MIT