Deputy MCP lets an AI agent securely read your Deputy shifts, timesheets, and team schedule from your local machine, and optionally act on them if you enable writes.
Connection & identity: deputy_whoami verifies credentials, company, timezone, clocked-in status, and calendar feed.
Your roster: deputy_get_my_roster lists your upcoming shifts in a date range; deputy_next_shift finds your next shift.
Your calendar: deputy_get_my_calendar_url returns your personal iCal subscription link for external calendar apps.
Read-only by default: no writes unless DEPUTY_ALLOW_WRITES=true; action tools only exist then.
Actions (optional): clock in/out, set unavailability, request shift swaps, and claim open shifts (with confirmation).
Team/manager tools (with manager access): team rosters, who is working, employee info, and shift search.
Flexible auth: API token, OAuth for employees, or a read-only calendar feed.
Local and private: credentials stay in your OS keychain and requests only go to your Deputy instance.
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, talks only to your Deputy install, 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. For Claude Code:
claude mcp add deputy \
-e DEPUTY_API_TOKEN=your-deputy-token \
-e DEPUTY_BASE_URL=https://your-company.eu.deputy.com \
-- uvx --from git+https://github.com/augbastos/Deputy-MCP deputy-mcpClaude Desktop, other MCP clients and Docker: see docs/DESIGN.md.
Pick one:
Mode | Who it's for | What to set |
API token | Deputy admins |
|
OAuth | Any employee |
|
Calendar feed | No API access |
|
For OAuth, create a personal app at https://once.deputy.com/my/oauth_clients with the
redirect URI http://localhost:8823/callback. Tokens are stored in your OS keychain.
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_request_shift_swap,
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.
Your credentials stay local: tokens go only to https://*.deputy.com and 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.
Return the signed-in user's personal Deputy calendar (iCal) subscription URL.
Deputy publishes a per-user, read-only iCal feed of your roster (the CalendarURL on /api/v1/me). Add the returned link to any calendar app (Google Calendar, Apple Calendar, Outlook) to see your shifts there; it stays in sync as your roster changes. Works at any access level — it reads only your own /me record.
When NOT to use: to read the shifts themselves here (use deputy_get_my_roster or deputy_next_shift) — this only returns the subscription link.
Returns markdown (the subscription link, or a note that this install exposes none)
or, with response_format="json", an object {"calendar_url"} whose value is a
string or null. In iCal mode the feed URL is the configured secret and is never
printed; the tool confirms it is configured without revealing it.
| 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?
Although annotations already declare readOnlyHint=true, the description adds substantial behavioral context: it reads only the caller's own /me record, works at any access level, stays in sync with roster changes, returns markdown or a JSON object, and never prints the secret iCal feed URL. No contradiction with annotations exists.
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 purpose is front-loaded, and every subsequent sentence adds distinct operational, security, or output-format context. There is no filler or redundant restatement of the 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?
The description fully covers tool selection, read-only behavior, access-level guarantees, output format variants, null handling, and the security nuance around the secret iCal URL. An agent has everything needed to call this tool correctly and avoid misuse.
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?
The schema already fully documents response_format with enum values and a default description, so the baseline is 3. The description goes beyond by specifying the exact JSON shape ({'calendar_url'}), the null possibility, and the markdown-mode behavior, which adds meaningful semantic value.
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 opens with a specific verb and resource: return the signed-in user's personal Deputy calendar (iCal) subscription URL. It also explicitly distinguishes this from sibling tools like deputy_get_my_roster and deputy_next_shift, which read shifts rather than return a subscription link.
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?
The description contains an explicit 'When NOT to use' section that names the alternative tools for reading shifts and clarifies that this tool only returns the subscription link. This gives the agent clear selection criteria with no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the signed-in user's own upcoming shifts in a date range.
Defaults to today through the next 7 days, computed in UTC; dates are ISO YYYY-MM-DD.
When NOT to use: for other people's shifts (use deputy_get_team_roster) or for worked time (use deputy_get_my_timesheets) — this returns your scheduled shifts.
Returns markdown (a shift list, times in the install timezone) or, with response_format="json", a list of Roster records. The output is identical whether the roster came from the Deputy API or, in iCal mode, from your calendar feed.
| 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?
The description discloses the default date range, UTC computation, ISO date format, output format behavior, timezone rendering, and the source-agnostic nature of the output (Deputy API or iCal feed). It does not contradict the readOnlyHint/openWorldHint annotations and actually enriches them with meaningful runtime behavior.
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 organized with clear sections: what it does, defaults/format, when not to use, and return behavior. Every sentence carries useful information, and the most critical purpose statement is front-loaded. It is detailed without being bloated.
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?
For a simple, read-only, all-optional-parameter tool with a full output schema, this description covers everything an agent needs: the resource, the scope, default behavior, alternatives, output format selection, timezone handling, and data source nuance. No critical context is missing.
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?
The input schema already describes all 3 parameters with 100% coverage, so the description does not need to re-document them. It adds value by explaining the default range when start_date/end_date are omitted, and by describing what response_format changes about the returned output. Baseline is 3; the added context justifies 4.
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 opens with a specific verb and resource: 'List the signed-in user's own upcoming shifts in a date range.' It clearly distinguishes the tool from alternatives by naming deputy_get_team_roster and deputy_get_my_timesheets, and states what it does NOT return. This is unambiguous and immediately actionable.
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' guidance names the sibling tools and the exact conditions that route elsewhere: other people's shifts go to deputy_get_team_roster, worked time goes to deputy_get_my_timesheets. It also specifies default behavior when date parameters are omitted, leaving no ambiguity about invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the single next upcoming shift for an employee (name or id).
Omit 'employee' to get your own next shift. A name must resolve to exactly one active person; otherwise the matches are listed for you to retry by id.
When NOT to use: for a full range of upcoming shifts (use deputy_get_my_roster or deputy_search_shifts) — this returns only the earliest one.
Returns markdown (one shift, or a 'none scheduled' note) or, with response_format="json", a single Roster record or null. In iCal mode only your own next shift is available (naming another employee needs an API token).
| 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?
With readOnlyHint=true already covering safety, the description adds valuable behavioral context: ambiguous-name handling, markdown vs. json return semantics, the 'none scheduled' note, and the iCal-mode auth limitation. No contradiction with annotations is present.
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 with the core purpose, then uses clear sections for usage and exclusions. Each sentence delivers distinct information—scope, edge cases, alternatives, and output behavior—with no wasted words.
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 has only two optional parameters and a read-only annotation. The description covers the essential usage scenarios, output formats, failure modes, and auth caveats. An output schema exists, so return value structure is already handled, making this complete for correct invocation.
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. The description adds meaning beyond the schema by explaining that a name must resolve to exactly one active person, that matches are listed for retry by id, and that json returns a single Roster record or null. This justifies a 4.
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 opens with a specific verb and resource: 'Return the single next upcoming shift for an employee (name or id).' It clearly distinguishes itself from sibling tools by noting it returns only the earliest one, contrasting with deputy_get_my_roster and deputy_search_shifts for full ranges.
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?
There is an explicit 'When NOT to use' section naming alternatives (deputy_get_my_roster, deputy_search_shifts) and the condition that selects this tool. It also gives guidance on omitting 'employee' for your own shift and handling ambiguous names, leaving no inference burden on the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify the Deputy connection and confirm which identity the token uses.
Returns who the API token authenticates as, the company/location and its timezone, whether that user is clocked in right now (from their in-progress timesheet), and their personal iCal calendar subscription URL when the install exposes one. Run this first to confirm setup before other tools.
When NOT to use: to read schedules or people (use deputy_get_my_roster or deputy_get_employee_info) — this only checks the connection and identity.
Returns markdown (a connection summary: signed-in name, company, timezone, whether
clocked in, and the calendar feed) or, with response_format="json", an object
{"whoami", "company", "timezone", "company_name", "clocked_in", "calendar_url"}
where clocked_in is a bool and calendar_url is a string or null. In iCal
mode there is no API identity, so this reports mode=iCal and that only your roster
is available.
| 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 signal read-only and open-world behavior, so the bar is lower. The description adds useful context: markdown vs JSON output, the exact JSON fields, clocked_in being a bool, calendar_url being nullable, and the special iCal mode with no API identity.
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 well organized with clear paragraphs for purpose, usage, and return behavior. Some redundancy exists between the opening summary and the later markdown/JSON explanation, but each section adds detail and the purpose is front-loaded.
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?
For a simple, one-optional-parameter read-only tool, this description covers the key aspects: what it returns, when to run it, when not to use it, alternatives, and a non-obvious iCal limitation. The output schema also exists to carry return-type details, so nothing critical is missing.
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% for the single response_format parameter, so the baseline is 3. The description adds value by explaining what json mode returns, including the object shape and field types, which is not fully captured by the schema's 'raw records' phrasing.
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 opens with a specific verb and resource: 'Verify the Deputy connection and confirm which identity the token uses.' It also distinguishes itself from sibling schedule/people-reading tools by stating 'this only checks the connection and identity.'
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 guidance is given: 'Run this first to confirm setup before other tools.' The description also states when not to use it and names alternatives: 'to read schedules or people (use deputy_get_my_roster or deputy_get_employee_info).'
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 clear primary purpose, and the explicit 'When NOT to use' notes help separate roster listing from next-shift lookup. There is minor overlap where whoami also returns the calendar URL and next_shift is a single-item subset of the roster, but these are not likely to cause serious misselection.
All tools share the deputy_ prefix and use snake_case, and three of the four follow a get_my_* pattern. deputy_whoami and deputy_next_shift break the verb-first convention, but the naming remains predictable and readable.
Four tools is a reasonable, compact set for a personal roster/identity assistant. It feels slightly thin for a general Deputy integration, especially since several missing tools are referenced in descriptions, but the count itself is not excessive.
The self-service schedule workflow is covered, but the descriptions reference four tools that do not exist in this server: deputy_get_employee_info, deputy_get_team_roster, deputy_get_my_timesheets, and deputy_search_shifts. There are also no leave, timesheet, or shift-management tools, so common Deputy queries will hit dead ends.
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.
