keeping-mcp

Open-source Model Context Protocol (MCP) server that exposes the Keeping (api.keeping.nl) time-tracking API as tools an AI coding assistant can call. Built for solo developers who use Claude Code (or any MCP-capable client) and want their billable hours logged into Keeping at the end of a session instead of typed in by hand, while keeping Keeping's existing native Jortt invoicing integration intact. Every write tool is dry-run by default — your hours never reach Keeping until you explicitly confirm.

⚠ Writes are dry-run BY DEFAULT

Every write tool (keeping_add_entry, keeping_update_entry, keeping_delete_entry, keeping_start_timer, keeping_stop_timer, keeping_resume_timer) returns a preview unless you pass confirm: true in the tool call.

Setting KEEPING_REQUIRE_CONFIRM=false in your environment disables this gate. Writes then happen on the first call — there is no second chance.

Recommendation: never disable this gate unless you are running the server in a non-interactive automation context and have explicitly accepted the loss of the confirmation step.

Install

From npm

No install required — npx fetches the package on first run:

KEEPING_TOKEN=kp_live_your_token_here npx -y keeping-mcp

The server speaks the MCP stdio protocol and stays in the foreground waiting for JSON-RPC frames on stdin — exit with Ctrl+C. In practice you do not run it by hand; an MCP-capable client (Claude Code, Claude Desktop, Cursor, etc.) spawns it for you using the config snippets below.

Optional — install globally so keeping-mcp is on your PATH:

npm install -g keeping-mcp
KEEPING_TOKEN=kp_live_your_token_here keeping-mcp

Requires Node.js >=22. The package is published to npmjs.com/package/keeping-mcp with sigstore provenance attestations.

Claude Code on Windows 11

Add to %APPDATA%\Claude\claude_desktop_config.json or to your project's .mcp.json file.

{
  "mcpServers": {
    "keeping-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "keeping-mcp"],
      "env": {
        "KEEPING_TOKEN": "kp_live_your_token_here"
      }
    }
  }
}

The cmd /c wrapper is required on Windows — npx resolves to npx.cmd, and Claude Code's process spawn does not search PATHEXT extensions (see anthropics/claude-code#58510).

Claude Code on macOS / Linux

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux), or your project's .mcp.json.

{
  "mcpServers": {
    "keeping-mcp": {
      "command": "npx",
      "args": ["-y", "keeping-mcp"],
      "env": {
        "KEEPING_TOKEN": "kp_live_your_token_here"
      }
    }
  }
}

Other MCP clients

Any MCP-capable client that supports the stdio transport works. The server is started by npx -y keeping-mcp and reads KEEPING_TOKEN from its environment. Discoverable in the MCP Registry as io.github.Red-Square-Software/keeping-mcp.

Get a Keeping access token

1. Sign in to your Keeping account.
2. Open Preferences (top-right menu).
3. Find the section Show features for developers and enable it.
4. A new Personal access tokens section appears.
5. Click Generate new token, name it (e.g. "Claude Code"), and copy the value.
6. Store it as KEEPING_TOKEN in your shell environment OR in your Claude Code config env block.

The token has full read+write access to your time entries — treat it like a password. Never commit it to git, never paste it into a chat, never read it back from a tool response (keeping-mcp

... View full README on GitHub