This server provides read-only access to your own Deputy roster via a personal iCal calendar feed.
Check whether the Deputy connection is active and reports iCal-feed-only mode.
Confirm that your personal calendar feed is configured, without revealing the secret feed URL.
List your own shifts for a date range, defaulting to today through the next 7 days.
Get your next upcoming shift, or confirm that none is scheduled.
Return results as human-readable markdown or raw JSON.
Times are shown in UTC in this mode.
Team/manager tools, timesheets, colleague lookup, OAuth sign-in, and write actions are not available in this configuration.
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
Python 3.11 or newer
A Deputy account (see the access modes below)
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.
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
Sign-in (OAuth credentials set): deputy_login
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 same client works as a command-line tool. With no subcommand, deputy-mcp starts
the MCP server (stdio by default; local HTTP is described in the
design notes).
deputy-mcp whoami # who the credentials belong to
deputy-mcp roster [--team] # your roster, or everyone's with manager access
deputy-mcp next [--employee NAME_OR_ID]
deputy-mcp timesheets | who | areas
deputy-mcp login [--no-browser] | logoutAdd --json for machine output.
uv sync # runtime and dev dependencies
uv run pytest # no network needed
uv run ruff check .
uv run mypySee CONTRIBUTING.md for the full list of checks.
Path | Contents |
| The package: |
| Unit, client, server and agent-interface tests; |
| |
| A mock Deputy server ( |
| CI, security scans and release |
Pushing a v* tag runs the release workflow (.github/workflows/release.yml). Release
notes are in the changelog.
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"}.
Inputs: response_format. Returns: result
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.
Inputs: end_date, start_date, response_format. Returns: result
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.
Inputs: employee, response_format. Returns: result
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"}.
Inputs: response_format. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored 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 for Arcoro and ExakTime — workforce data, jobs, cost codes and locations.
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.
