Ask Deputy about your schedule, roster, and timesheets, and optionally act on shifts through an MCP server.
Verify the Deputy connection/identity, company, timezone, clock-in status, and calendar feed.
Get your personal Deputy iCal calendar subscription URL.
List your upcoming shifts for a date range (defaults to today through the next 7 days).
Find your next shift, or another employee’s next shift by name/id.
Read timesheets, colleagues, areas, team roster, who’s working, employee info, and search shifts (per README; manager access as applicable).
With writes enabled, clock in/out, set unavailability, and claim open shifts after confirmation.
Connect via employee OAuth, admin API token, or read-only calendar feed.
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., "@deputy-mcp show my next shift"
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.
Ask Claude "when do I work next?" and get the answer from your Deputy roster.
Deputy MCP is a local MCP server that lets AI agents read your shifts, timesheets and team schedule, and, only if you turn it on, act on them. It runs on your machine, connects to Deputy, and works with a regular employee account.
"When do I work next?"
"How many hours did I work last week?"
"Who's on shift right now?" (manager access)
"Clock me in." (writes enabled)
"Take the open shift on Saturday." (writes enabled; asks you to confirm first)
Related MCP server: SmartSuite MCP Server
Needs uv and Python 3.11 or newer. Choose your access mode first:
Mode | Who it's for | Start here |
OAuth | Any employee | |
API token | Deputy admins | |
Calendar feed | No API access | Set |
Create a personal app at https://once.deputy.com/my/oauth_clients with the redirect
URI http://localhost:8823/callback. Create it there, not under your install's
Settings → Developer: an app made inside an install fails sign-in with
invalid_client. In Bash, replace the placeholders, sign in, then register the
server with Claude Code:
export DEPUTY_OAUTH_CLIENT_ID='your-client-id'
export DEPUTY_OAUTH_CLIENT_SECRET='your-client-secret'
uvx deputy-mcp login
claude mcp add deputy \
-e DEPUTY_OAUTH_CLIENT_ID="$DEPUTY_OAUTH_CLIENT_ID" \
-e DEPUTY_OAUTH_CLIENT_SECRET="$DEPUTY_OAUTH_CLIENT_SECRET" \
-- uvx deputy-mcpLogin opens your browser and stores OAuth tokens in your OS keychain by default.
Run login and Claude Code as the same OS user. No terminal (for example, the Claude
Desktop bundle)? Set the two OAuth values and ask the assistant to sign you in: the
deputy_login tool opens the same browser sign-in.
With your Deputy API token and install URL, register directly; no OAuth login is needed:
claude mcp add deputy \
-e DEPUTY_API_TOKEN=your-deputy-token \
-e DEPUTY_BASE_URL=https://your-company.eu.deputy.com \
-- uvx deputy-mcpFor your own roster, replace ... with your private calendar feed URL:
codex mcp add deputy --env DEPUTY_CALENDAR_URL=... -- uvx deputy-mcpThe first uvx run downloads dependencies; if Codex reports the tools as unavailable,
set startup_timeout_sec = 60 under [mcp_servers.deputy] in ~/.codex/config.toml.
Claude Desktop users: download the .mcpb bundle from the Releases page
and drag it onto Settings → Extensions (double-clicking may not open it on Windows). Fill
in one access mode under Configure, then ask Claude to sign you in.
Other MCP clients and Docker: see other ways to install.
All settings are listed in .env.example.
Your data (any account): deputy_whoami, deputy_get_my_roster,
deputy_next_shift, deputy_get_my_timesheets, deputy_get_my_colleagues,
deputy_get_my_calendar_url, deputy_get_areas
Team (manager access): deputy_get_team_roster, deputy_who_is_working,
deputy_get_employee_info, deputy_search_shifts
Actions (only with DEPUTY_ALLOW_WRITES=true): deputy_clock_in,
deputy_clock_out, deputy_set_unavailability,
deputy_claim_open_shift
Read-only unless you set DEPUTY_ALLOW_WRITES=true; until then the action tools
don't exist for the agent.
You confirm before a shift is claimed, since that skips Deputy's approval step.
No guessing: if a name matches several people, you get the list, not the first one.
Credential protection: by default, tokens go only to https://*.deputy.com
and OAuth tokens live in your OS keychain; errors are scrubbed of secrets before
an agent sees them.
The everyday read tools and OAuth sign-in were tested against a real Deputy install with an employee account. Manager tools, actions and the OAuth token refresh are covered by automated tests but not yet verified on a live install. Not affiliated with Deputy.
Confirm that your personal calendar feed is configured. The feed link itself is a secret in this mode and is never shown.
When NOT to use: to read the shifts in the feed (use deputy_get_my_roster).
Returns markdown or, with response_format="json", an object {"mode", "configured", "calendar_url"}.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output format: 'markdown' (human-readable, default) or 'json' (raw records). | markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is read-only and open-world. The description adds important behavior beyond them by stating that the feed link is secret and never shown, though the returned calendar_url field creates minor ambiguity about what is actually exposed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and structured into purpose, when-not-to-use, and return format. Every sentence contributes useful information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and an output schema exists, so return values need not be explained in depth. The description still covers configuration checking, secret handling, and the main alternative, though the calendar_url return field remains slightly ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single response_format parameter is fully documented by the schema. The description reinforces its effect on return shape but adds little parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and scope: confirm that the personal calendar feed is configured. It also distinguishes this from reading shifts by naming deputy_get_my_roster explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit when-not-to-use case and points to the correct alternative, deputy_get_my_roster. The first sentence also implies when to use it: checking whether the calendar feed is configured.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your own shifts in a date range from your personal Deputy calendar feed. Defaults to today through the next 7 days; dates are ISO YYYY-MM-DD. Times are shown in UTC in this mode.
When NOT to use: for only the single next shift (use deputy_next_shift).
Returns markdown (a shift list) or, with response_format="json", a list of Roster records.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | End date (ISO). | |
| start_date | No | Start date (ISO). | |
| response_format | No | Output format: 'markdown' (human-readable, default) or 'json' (raw records). | markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description correctly focuses on operational behavior: the default window of today through +7 days, ISO date format, and the UTC timezone caveat in this mode. Missing only deeper traits like pagination or large-result handling, so it falls short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact blocks—behavior, exclusion, returns—with the core purpose front-loaded and no filler. Every sentence carries non-redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A read-only, three-optional-parameter tool with a full output schema; the description covers defaults, formats, timezone, sibling routing, and output shape. Nothing an agent needs in order to call it correctly is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the description earns an extra point by explaining what the null defaults actually do ('defaults to today through the next 7 days') and by specifying ISO YYYY-MM-DD, which the schema only hints at with 'ISO'. The response_format enum is echoed rather than elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List your own shifts in a date range') plus the data source ('your personal Deputy calendar feed'), which precisely delimits it from broader roster tools. The closing line about the single-next-shift sibling makes the boundary unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When NOT to use' clause names the alternative tool (deputy_next_shift) and the exact condition that selects it. An agent can route between the two without opening either schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return your own next upcoming shift from your personal Deputy calendar feed. Leave 'employee' empty: other people's shifts are not available in this mode.
When NOT to use: for a range of shifts (use deputy_get_my_roster).
Returns markdown (one shift, or a note that none is scheduled) or, with response_format="json", a single Roster record or null.
| Name | Required | Description | Default |
|---|---|---|---|
| employee | No | Employee name or id. | |
| response_format | No | Output format: 'markdown' (human-readable, default) or 'json' (raw records). | markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds a real capability boundary ('other people's shifts are not available in this mode') and the return shapes (markdown note vs single Roster record or null). It stops short of saying what actually happens if a non-empty 'employee' is supplied — error, silent ignore, or fallback — which is the one behavioral unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short blocks — purpose, when-not, return shape — with the scoping constraint front-loaded. No filler sentences and no repetition of the annotations or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and annotations cover read-only behavior, so the description is not obligated to explain return values, yet it does so concisely (markdown / Roster record / null). The only gap is the undefined behavior when 'employee' is populated, which matters for a tool whose whole design hinges on that field being empty.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the 'employee' field is documented as 'Employee name or id' yet the description tells the caller to leave it empty and explains why (other people's shifts are unavailable). That is genuinely corrective guidance rather than a restatement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return your own next upcoming shift') plus the data source ('personal Deputy calendar feed'), which is enough to distinguish it from deputy_get_my_roster and deputy_get_my_calendar_url. The scope word 'next' and 'own' are the discriminating qualifiers an agent needs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the when-not case ('for a range of shifts') and routes to the specific sibling to use instead (deputy_get_my_roster). It also tells the agent how to call it correctly by instructing to leave 'employee' empty.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm the Deputy connection. In this configuration (iCal feed mode, no API token) it reports that only your own roster is available.
When NOT to use: to read your shifts (use deputy_get_my_roster or deputy_next_shift).
Returns markdown or, with response_format="json", an object {"mode", "roster_only", "available_tools"}.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output format: 'markdown' (human-readable, default) or 'json' (raw records). | markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and open-world, but the description adds important context about iCal feed mode, no API token, roster-only availability, and the returned fields. This is useful behavioral detail beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded, tightly scoped, and uses separate sentences for purpose, exclusions, and return behavior without unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers connection confirmation, configuration limits, alternative tools, and output shape. With an output schema present, this is more than complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the response_format parameter is already documented in the schema. The description still adds value by naming the JSON return object fields and restating the markdown/json behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Confirm the Deputy connection.' It also clarifies the configuration-specific behavior and explicitly distinguishes this tool from shift-reading siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit 'When NOT to use' section and names the correct alternatives, deputy_get_my_roster and deputy_next_shift, for reading shifts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0deputy_get_my_calendar_urldeputy_get_my_rosterdeputy_next_shiftdeputy_whoamiScored across 4 tools
Each tool has a distinct role (config check, date-range roster, single next shift, connection status) and descriptions include explicit 'When NOT to use' cross-references that steer selection well. The only soft overlap is between deputy_whoami and deputy_get_my_calendar_url, which both act as 'confirm configuration' probes and could be confused by an agent wanting a simple health check.
All four tools share the deputy_ prefix and are snake_case, giving a predictable, readable surface. Minor deviation: two are verb_noun (get_my_roster, get_my_calendar_url) while next_shift drops the verb and whoami is a conventional standalone name.
Four tools is a tight, well-scoped set for a read-only personal-roster integration, and each tool covers a real user intent. It sits at the thin end of the scale, but nothing feels redundant or padded for the stated iCal-feed mode.
For the declared read-only personal calendar domain, the surface is essentially complete: identity/mode check, configuration check, a date-range shift list, and a next-shift shortcut, with both markdown and JSON outputs. Gaps are deliberate (no team visibility, no write/lifecycle operations), so agents cannot get stuck on covered workflows but also cannot do anything beyond reading their own shifts.
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
MCP server providing attendance data queries via the CloudTime API.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
