workbook-mcp

Local MCP server for Deltek Workbook — manage time entries from Claude Code.

Prerequisites

• Node.js 22+
• Google Chrome or Microsoft Edge installed
• A Workbook account using Okta SSO

Install

The server is published to npm, so there's nothing to clone or build. Register it with Claude Code, replacing the tenant URL with your own:

claude mcp add workbook -- cmd /c npx -y workbook-mcp@latest --tenant https://merkle-ne.workbook.net

The -- after claude mcp add passes the rest of the command verbatim to the spawned process — without it, the --tenant flag would be consumed by claude mcp itself.

Or, if your project already includes a .mcp.json, just open it in Claude Code and approve the trust prompt — the entry looks like this:

{
  "mcpServers": {
    "workbook": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "workbook-mcp@latest", "--tenant", "https://merkle-ne.workbook.net"]
    }
  }
}

On macOS/Linux, drop the cmd /c and use "command": "npx" directly.

First use

Just ask Claude to do something Workbook-related — for example:

"Show me my pinned Workbook tasks for this week."

The first time, a Chrome window will open for Okta SSO. Complete sign-in (and 2FA if prompted); the window closes itself once authenticated and the tool returns its result. Your session is remembered after that. When cookies eventually expire, the next tool call transparently re-opens the browser — which usually auto-completes because your persistent profile remembers Okta.

Tools

| Tool | What it does | |---|---| | list_my_tasks | Your weekly timesheet rows (each with a pinned flag, plus job/task/activity IDs) | | create_time_entry | Register a new entry. Supports dryRun: true to preview the payload without sending. | | update_time_entry | Update fields on an existing entry by ID | | workbook_session_status | Active health check — is auth alive? | | workbook_refresh_session | Manually re-authenticate (otherwise auto-triggered on expiry) | | workbook_session_info | Local diagnostic — what's loaded? (no API call) |

Data location

Persistent state lives in ~/.workbook-mcp/:

• storageState.json — captured cookies
• workbook-config.json — cached resource ID
• browser-profile/ — persistent Chrome profile that remembers Okta between captures
• metadata/ — Workbook API metadata (only present if you ran capture with --metadata)

Safe to delete the whole directory if you want a fully fresh start.

Troubleshooting

• MCP server won't register — make sure claude mcp add includes the -- separator and that the tenant URL is correct.
• No browser opens on first use — install Chrome or Edge. As a fallback, run npx playwright install chromium once to install a bundled Chromium browser.
• "Session expired" persists after auto-refresh — clone the repo and run npm run capture -- --tenant <url> from a terminal to see the capture flow directly; that often surfaces network, proxy, or Okta issues that aren't visible through Claude Code.
• Wrong tenant — if you registered with the wrong --tenant, run claude mcp remove workbook then re-add with the correct URL.

Developing

If you want to hack on the server itself:

git clone https://github.com/APMerkle/workbook-mcp.git
cd workbook-mcp
npm install
npm run build

Point Claude Code at your local build instead of the published package:

claude mcp add workbook-dev -- node "C:\path\to\workbook-mcp\dist\index.js" --tenant https://merkle-ne.workbook.net

The capture flow can also be triggered manually from a terminal:

npm run capture -- --tenant https://merkle-ne.workbook.net

Add --metadata to also re-download the Workbook API metadata (only needed if extending the project):

npm run capture -- --tenant https://merkle-ne.workbook.net --metadata

Publishing a new version

# bump the version in package.json, then:
npm publish

prepublishOnly runs tsc automatically, so dist/ is always fresh on publish. Colleagues using workbook-mcp@latest in their .mcp.json pick up the new version on the next Claude Code session.