Deputy MCP

Deputy MCP

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.

What you can ask

• "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)

Install

Needs uv and Python 3.11 or newer. Choose your access mode first:

Mode	Who it's for	Start here
OAuth	Any employee	Employee sign-in
API token	Deputy admins	Admin setup
Calendar feed	No API access	Set DEPUTY_CALENDAR_URL using the client setup; your own roster only, read-only

Employee OAuth

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-mcp

Login 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.

Admin API token

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-mcp

Codex CLI

For your own roster, replace ... with your private calendar feed URL:

codex mcp add deputy --env DEPUTY_CALENDAR_URL=... -- uvx deputy-mcp

The 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.

Tools

• 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

Safe by default

• 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.

Status

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.

More

• How it's built and why
• Contributing · Security · Changelog · Roadmap

License

MIT