@shyftplan/mcp-server

Model Context Protocol server for shyftplan. Exposes shyftplan's GraphQL API as MCP tools that any MCP-compatible client (Claude Desktop, VS Code, Cursor, Zed, …) can call.

Quickstart

One command, one confirmation click:

npx @shyftplan/mcp-server init cursor
# or: claude-desktop, vscode, zed

init chains auth and install <host> together:

1. It opens shyftplan in your browser (or asks you which environment to target if it's your first run).
2. You approve the request on the shyftplan pairing page.
3. Your terminal receives the token over a loopback callback — nothing is copy-pasted, nothing hits your shell history.
4. The host config is written (with a .shyftplan-backup alongside if there was already a file there).

Restart the host and shyftplan tools become available immediately.

Prefer to run the steps separately? The lower-level commands still work:

npx @shyftplan/mcp-server auth
npx @shyftplan/mcp-server install cursor

Once installed, verify the whole setup at any time with:

npx @shyftplan/mcp-server doctor

doctor prints a per-check ✔/✘ report of the config file, the token's validity against /api/v1/mcp/access_metadata, the apollo-mcp-server binary, and the host configs it can find.

Prefer to edit config files by hand?

For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "shyftplan": {
      "command": "npx",
      "args": ["-p", "@shyftplan/mcp-server", "shyftplan-mcp"]
    }
  }
}

The -p pkg cmd form is portable across npm 6-era npx and modern npx (npm 7+). The shortcut -y @shyftplan/mcp-server only works on modern npx — legacy installs fail with You must supply a command.

The start command is implicit — running shyftplan-mcp with no args behaves the same as shyftplan-mcp start.

When the CLI can't reach 127.0.0.1

Some setups can't host the loopback listener the default auth flow uses — SSH sessions, dev containers, or networks that block ephemeral inbound ports. Add --manual to fall back to a copy-paste flow:

npx @shyftplan/mcp-server auth --manual
# or:
npx @shyftplan/mcp-server init cursor --manual

The wrapper prints an authorize URL and waits at a prompt. Open the URL in any browser (even on a different device), approve the request, then paste the token shown on the confirmation page back into the terminal.

Requirements

• A shyftplan account with an accessible company.
• Node.js 20 or newer — recommended. If you're on an older Node, the wrapper detects that at startup, downloads Node.js LTS into $XDG_CACHE_HOME/shyftplan-mcp/node-lts/ (one-time, ~40 MB), and re-execs itself. To opt out, set SHYFTPLAN_MCP_SKIP_NODE_DOWNLOAD=1. To bring your own runtime, set SHYFTPLAN_MCP_NODE=/path/to/node.

The apollo-mcp-server binary is fetched automatically on first start (pinned to v1.17.0-shyftplan.0 from a fork that adds server_info.icons — cached under $XDG_CACHE_HOME/shyftplan-mcp/bin/ or %LOCALAPPDATA%\shyftplan-mcp\bin\ on Windows). Force-fetch ahead of time with:

npx @shyftplan/mcp-server download-binary

To use an already-installed apollo-mcp-server instead of the auto-download, set APOLLO_MCP_SERVER_BIN to its absolute path.

What you can do with it

Nine curated read-only tools ship in v0.1:

| Tool | What it returns | | --- | --- | | WhoAmI | Signed-in user + their default company. | | ListLocations | Locations for a company. | | ListPositions | Positions for a company. | | ListLocationsPositions | Position-location matrix. | | ListEmployments | Employees, filterable by location / position. | | ListShiftSchedules | Published shift schedules. | | ListShiftPresets | Named shift preset templates. | | ListShiftSystems | Shift rotation systems. | | ListAbsenceReasons | Absence reason catalog. |

Every list tool requires a companyId — get it from WhoAmI first.

Writes (creating shifts, editing absences, …) will land in a future release behind an explicit toggle. Nothing this package does today can change your shyftplan data.

Commands

shyftplan-mcp                       # equivalent to `shyftplan-mcp start`
shyftplan-mcp init <host>           # one-shot: auth + install <host>
shyftplan-mcp auth [--manual]       # trigger the browser (or manual) auth flow
shyftplan-mcp start                 # spawn apollo-mcp-server with saved token
shyftplan-mcp doctor                # health-check config + token + binary + hosts + wrapper version
shyftplan-mcp update [--check-only] # clear the npx cache so the next host restart pulls a newer version
shyftplan-mcp install <host>        # write config for an MCP host (see below)
shyftplan-mcp install --list        # list supported hosts + their config paths
shyftplan-mcp download-binary       # force-fetch apollo-mcp-server into the cache
shyftplan-mcp --help                # full flag list
shyftplan-mcp --version

Keeping the wrapper up to date

Every host config generated by install uses npx -p @shyftplan/mcp-server shyftplan-mcp. npx caches installations under ~/.npm/_npx/ and re-checks the npm registry manifest on each invocation; when a newer version is published, the next host restart picks it up transparently.

If you want to force the update sooner (npx's manifest cache TTL is a few minutes) or after a bad publish:

npx @shyftplan/mcp-server update

That clears the _npx cache and prints the installed / latest version pair. Restart your MCP host after running it.

shyftplan-mcp update --check-only prints the same version diff without touching any cache — useful in CI.

Registering with a host

install <host> writes an mcpServers entry (or its host-specific equivalent) into the host's on-disk config. The merge preserves every other key and every other server you might already have configured.

Supported hosts:

| Host id | Config file (macOS) | Schema | | --- | --- | --- | | claude-desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | mcpServers.<name> | | cursor | ~/.cursor/mcp.json | mcpServers.<name> | | vscode | ~/Library/Application Support/Code/User/mcp.json | servers.<name> (type stdio) | | zed | ~/.config/zed/settings.json | context_servers.<name> |

Windows and Linux paths follow the equivalent conventions (%APPDATA%\… and $XDG_CONFIG_HOME/…). Run install --list to see the exact path for your machine.

If the target config already exists, install writes a <path>.shyftplan-backup copy of the original before overwriting.

By default the server entry is keyed under "shyftplan". Use --server-name to install multiple entries side-by-side, e.g. one against production and one against a beta endpoint:

npx @shyftplan/mcp-server install cursor --server-name shyftplan-beta

Configuration

The auth command writes to ~/.config/shyftplan-mcp/config.json (macOS/Linux) or %APPDATA%\shyftplan-mcp\config.json (Windows). The file is created with 0o600 permissions and contains:

{
  "endpoint": "https://shyftplan.com",
  "token": "<secret>",
  "clientName": "shyftplan-mcp-cli"
}

To revoke a token, delete it from your shyftplan profile under Profile → Security → API tokens. Deleting the config file locally does the same thing on your machine.

Environment variables

| Variable | Purpose | | --- | --- | | SHYFTPLAN_ENDPOINT | Overrides the endpoint (e.g. beta URL). Same as --endpoint. | | APOLLO_MCP_SERVER_BIN | Absolute path to an existing apollo-mcp-server binary. When set, skips the auto-download. | | XDG_CONFIG_HOME | Overrides the shyftplan-mcp config directory root on Linux/macOS. | | XDG_CACHE_HOME | Overrides the cache directory for the auto-downloaded apollo-mcp-server binary on Linux/macOS. |

Flags

| Flag | Applies to | Default | | --- | --- | --- | | --endpoint <url> | auth, start | https://shyftplan.com | | --client-name <name> | auth | shyftplan-mcp-cli — shown in your token's audit trail. | | --server-name <name> | install | shyftplan — JSON key written into the host's config. | | --list | install | Print each supported host and its resolved config path, then exit. |

Security notes

• Tokens are transmitted only via the URL fragment (#token=…), not the query string. Fragments are stripped by browsers before they hit any HTTP log.
• The state parameter on the callback is a cryptographically random one-time value. A rogue local process racing your browser tab is caught and rejected.
• The loopback callback listener binds to 127.0.0.1 on an ephemeral port and shuts down as soon as the flow completes (or times out).
• The token lives in a file with 0o600 permissions inside your XDG config directory. It is never emitted to stdout or the terminal.

Troubleshooting

• ERROR: You must supply a command (from npx) — You're on npm 6 or the standalone npx package. Legacy npx doesn't understand the -y shortcut and doesn't auto-invoke the bin when the bin name differs from the package name. Every host config generated by install uses the portable -p @shyftplan/mcp-server shyftplan-mcp form so this shouldn't happen from a fresh install. If you edited the args by hand, restore them (see Registering with a host).
• SyntaxError: Unexpected token '.' — Your system Node is older than 14 and can't parse optional chaining. The wrapper's launcher (bin/cli.cjs) detects this and downloads Node.js LTS into ~/.cache/shyftplan-mcp/node-lts/. If you see the raw SyntaxError instead of the download notice, you probably launched dist/cli.js directly — run the bin/cli.cjs entry (or use npx @shyftplan/mcp-server) so the launcher runs first.
• Failed to launch apollo-mcp-server: ENOENT — The auto-download landed the binary but something is wrong with its permissions (or your cache directory isn't executable). Run shyftplan-mcp download-binary to re-fetch, or set APOLLO_MCP_SERVER_BIN to a manually installed copy.
• Failed to download … HTTP 404 — Your platform / arch isn't covered by Apollo's release assets. Install apollo-mcp-server from source or via the shell installer (curl -sSL https://mcp.apollo.dev/download/nix/latest | sh) and set APOLLO_MCP_SERVER_BIN.
• Timed out waiting for the token callback — The default timeout is 5 minutes. Re-run shyftplan-mcp auth and complete the browser flow more quickly, or if you're on a locked-down network, use --manual to paste the token directly.
• State mismatch — Something raced your browser tab. Re-run the auth flow.
• No shyftplan-mcp config found — You haven't run shyftplan-mcp auth on this machine yet.

License

Proprietary. © shyftplan GmbH. All rights reserved.