English Français العربية

Deputy MCP

Official registry AI and agents

Deputy workforce data for AI agents: rosters, timesheets and shifts; read-only by default

Source code Website Documentation

What can you do with Deputy MCP?

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

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package deputy-mcp
Claude Code 
claude mcp add deputy-mcp -e 'DEPUTY_API_TOKEN=<your deputy_api_token>' -e 'DEPUTY_BASE_URL=<DEPUTY_BASE_URL>' -e 'DEPUTY_OAUTH_CLIENT_ID=<DEPUTY_OAUTH_CLIENT_ID>' -e 'DEPUTY_OAUTH_CLIENT_SECRET=<your deputy_oauth_client_secret>' -e 'DEPUTY_CALENDAR_URL=<your deputy_calendar_url>' -e 'DEPUTY_ALLOW_WRITES=false' -e 'DEPUTY_TOKEN_STORE=<DEPUTY_TOKEN_STORE>' -- uvx deputy-mcp==0.4.2
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "deputy-mcp": {
            "command": "uvx",
            "args": [
                "deputy-mcp==0.4.2"
            ],
            "env": {
                "DEPUTY_API_TOKEN": "<your deputy_api_token>",
                "DEPUTY_BASE_URL": "<DEPUTY_BASE_URL>",
                "DEPUTY_OAUTH_CLIENT_ID": "<DEPUTY_OAUTH_CLIENT_ID>",
                "DEPUTY_OAUTH_CLIENT_SECRET": "<your deputy_oauth_client_secret>",
                "DEPUTY_CALENDAR_URL": "<your deputy_calendar_url>",
                "DEPUTY_ALLOW_WRITES": "false",
                "DEPUTY_TOKEN_STORE": "<DEPUTY_TOKEN_STORE>"
            }
        }
    }
}

Environment variables

  • DEPUTY_API_TOKEN secret API token mode (all tools): a Deputy API token, created with an admin access level. Pair with DEPUTY_BASE_URL. Configure exactly one of the three authentication modes: API token, OAuth, or iCal feed.
  • DEPUTY_BASE_URL API token mode: your Deputy install origin, e.g. https://your-company.eu.deputy.com.
  • DEPUTY_OAUTH_CLIENT_ID OAuth mode (all tools, no admin needed): client id of a personal app registered at https://once.deputy.com/my/oauth_clients with redirect URI http://localhost:8823/callback. Run 'deputy-mcp login' once.
  • DEPUTY_OAUTH_CLIENT_SECRET secret OAuth mode: client secret of the same app.
  • DEPUTY_CALENDAR_URL secret iCal feed mode (your own roster only, read-only): your personal Deputy calendar link. It contains a private token.
  • DEPUTY_ALLOW_WRITES Set to true to register the write tools (API token and OAuth modes). Read-only by default.
  • DEPUTY_TOKEN_STORE OAuth mode: file path for a plaintext token store, only where no OS keychain is available. Default: the OS keychain.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Deputy MCP
  2. What you can ask
  3. Install
  4. Tools
  5. Safe by default
  6. Status
  7. More
  8. License

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:

ModeWho it's forStart here
OAuthAny employeeEmployee sign-in
API tokenDeputy adminsAdmin setup
Calendar feedNo API accessSet 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

License

MIT

Frequently asked questions

What is Deputy MCP?

Deputy workforce data for AI agents: rosters, timesheets and shifts; read-only by default

How do I install Deputy MCP?

It runs on your machine. In Claude Code: claude mcp add deputy-mcp -e 'DEPUTY_API_TOKEN=<your deputy_api_token>' -e 'DEPUTY_BASE_URL=<DEPUTY_BASE_URL>' -e 'DEPUTY_OAUTH_CLIENT_ID=<DEPUTY_OAUTH_CLIENT_ID>' -e 'DEPUTY_OAUTH_CLIENT_SECRET=<your deputy_oauth_client_secret>' -e 'DEPUTY_CALENDAR_URL=<your deputy_calendar_url>' -e 'DEPUTY_ALLOW_WRITES=false' -e 'DEPUTY_TOKEN_STORE=<DEPUTY_TOKEN_STORE>' -- uvx deputy-mcp==0.4.2. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Deputy MCP need an API key?

Yes. It expects DEPUTY_API_TOKEN, DEPUTY_OAUTH_CLIENT_SECRET, DEPUTY_CALENDAR_URL, which you set in its configuration.

Is Deputy MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Deputy MCP?

It is published by augbastos. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.