# Shiftbase MCP server

Connect Shiftbase to ChatGPT, Claude and any AI agent through Cotlet.dev. Review timesheets, decide leave requests and approve shift swaps in your signed-in Shiftbase account. Actions that affect other people ask for approval by default.

## What you can ask

> Approve last week's hours without conflicts.

> Approve leave that keeps 3 on shift.

> Approve swaps under 40 hours a week.

## Connect in 2 minutes

Get your API key at https://cotlet.dev/app and export it as `COTLET_API_KEY`.

### ChatGPT

Settings → Apps → add connector URL `https://cotlet.dev/mcp/v1`, then sign in with Cotlet.dev. No API key needed.

### Claude Code

```bash
claude mcp add --transport http cotlet https://cotlet.dev/mcp/v1 --header "Authorization: Bearer $COTLET_API_KEY"
```

### Cursor

Copy `.cursor/mcp.json` from this repo into your project:

```json
{
  "mcpServers": {
    "cotlet": {
      "url": "https://cotlet.dev/mcp/v1",
      "headers": {
        "Authorization": "Bearer ${COTLET_API_KEY}"
      }
    }
  }
}
```

## Run it locally (stdio)

This repo is a real MCP server. It speaks MCP over stdio, lists its Shiftbase tools without any key, and forwards every tool call to the hosted Cotlet.dev server. The hosted URL above stays the recommended way. Use this when your client only starts local servers.

Run the included Python module with Python 3.10 or later:

```bash
python3 shiftbase_agent.py serve
```

Or with Docker:

```bash
docker build -t shiftbase-mcp .
docker run -i --rm -e COTLET_API_KEY shiftbase-mcp
```

Tools: `shiftbase_guide`, `shiftbase_status`, `shiftbase_open`, `shiftbase_read`, `shiftbase_click`, `shiftbase_type`, `shiftbase_close`. Without `COTLET_API_KEY` a tool call answers: "Set COTLET_API_KEY. Get a key at https://cotlet.dev/app".

## Command line

Python 3.10+, with no third-party runtime dependencies. Clone this repository and run:

```bash
export COTLET_API_KEY="your-key"
python3 shiftbase_agent.py connect   # ready config for Claude Code, Cursor, ChatGPT
python3 shiftbase_agent.py status    # is Shiftbase ready in your Cotlet.dev account
python3 shiftbase_agent.py guide     # Shiftbase screens and sign-in link
python3 shiftbase_agent.py read      # open Shiftbase, read the page, close the browser
python3 shiftbase_agent.py tools     # list Cotlet.dev tools
python3 shiftbase_agent.py serve     # start the stdio MCP server (same as no argument)
```

## Questions from Shiftbase users

**Does this require the Shiftbase Public API token?**

No. Cotlet.dev works in your signed-in Cloud Browser account. Sign in to Shiftbase there and enable it for agents.

**Which permissions apply?**

Your Shiftbase role applies. Approving hours requires timesheet approval rights; exchanges require the Approve exchanges permission.

**Is this affiliated with Shiftbase?**

No. Cotlet.dev is independent and not affiliated with Shiftbase.

## Learn more

- [Shiftbase integration and hosted tools](https://cotlet.dev/integrations/shiftbase-api-mcp-server)

---

More: https://cotlet.dev/integrations/shiftbase-api-mcp-server?utm_source=github&utm_medium=readme&utm_campaign=shiftbase

Request access: https://cotlet.dev/signup?app=shiftbase&utm_source=github&utm_medium=readme&utm_campaign=shiftbase

## Workflows on the hosted integration

The live integration page documents these 13 operations:

- `list_departments`
- `list_employees`
- `list_shifts`
- `list_open_shifts`
- `list_timesheet_entries`
- `list_absence_requests`
- `list_exchange_requests`
- `add_worked_hours`
- `set_timesheet_status`
- `approve_absence_request`
- `decline_absence_request`
- `approve_exchange_request`
- `decline_exchange_request`

The local stdio adapter exposes seven browser helpers listed above. These helpers forward to Cotlet.dev; the workflow operations are documented on the hosted integration page.