Metadata-Version: 2.5
Name: deputy-mcp
Version: 0.3.0
Summary: Deputy MCP: an MCP server that gives AI agents safe, read-only-by-default access to Deputy rosters, timesheets and shifts
Project-URL: Homepage, https://github.com/augbastos/deputy-mcp
Project-URL: Repository, https://github.com/augbastos/deputy-mcp
Project-URL: Issues, https://github.com/augbastos/deputy-mcp/issues
Project-URL: Changelog, https://github.com/augbastos/deputy-mcp/blob/main/CHANGELOG.md
Author: Augusto Bastos
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,claude,deputy,mcp,model-context-protocol,oauth2,roster,scheduling,timesheets,workforce-management
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastmcp<5,>=4.0.3
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25
Requires-Dist: pydantic>=2.12
Requires-Dist: python-dotenv>=1.0
Requires-Dist: tzdata>=2024.1
Description-Content-Type: text/markdown

# Deputy MCP

<!-- mcp-name: io.github.augbastos/deputy-mcp -->

[![CI](https://github.com/augbastos/deputy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/augbastos/deputy-mcp/actions/workflows/ci.yml)
[![Security](https://github.com/augbastos/deputy-mcp/actions/workflows/security.yml/badge.svg)](https://github.com/augbastos/deputy-mcp/actions/workflows/security.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Ask Claude *"when do I work next?"* and get the answer from your
[Deputy](https://www.deputy.com) roster.

Deputy MCP is a local [MCP](https://modelcontextprotocol.io) 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](https://docs.astral.sh/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](#employee-oauth) |
| **API token** | Deputy admins | [Admin setup](#admin-api-token) |
| **Calendar feed** | No API access | Set `DEPUTY_CALENDAR_URL` using the [client setup](docs/DESIGN.md#other-mcp-clients); 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`. In Bash, replace the placeholders, sign in,
then register the server with Claude Code:

```bash
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.

### Admin API token

With your Deputy API token and install URL, register directly; no OAuth login is needed:

```bash
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:
```bash
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: look for the `.mcpb` bundle on the [Releases page](https://github.com/augbastos/deputy-mcp/releases).
Other MCP clients and Docker: see [other ways to install](docs/DESIGN.md#other-ways-to-install).
All settings are listed in [`.env.example`](.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_request_shift_swap`,
  `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](docs/DESIGN.md)
- [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md)

## License

[MIT](LICENSE)
