# Clocknext MCP server

> Meter usage and manage usage-based billing for AI tools directly from AI coding agents and MCP clients.

- Repository: https://github.com/Clocknext/clocknext-mcp
- Page: https://hostedmcp.org/servers/clocknext/mcp
- Transport: stdio
- Stars: 0
- Latest version: 0.13.0

## Install

### Claude Code

```sh
claude mcp add --env 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' mcp -- npx -y @clocknext/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@clocknext/mcp"
      ],
      "env": {
        "CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@clocknext/mcp"
      ],
      "env": {
        "CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@clocknext/mcp"],"env":{"CLOCKNEXT_API_KEY":"<YOUR_CLOCKNEXT_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@clocknext/mcp"
      ],
      "env": {
        "CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add mcp --env 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' -- npx -y @clocknext/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp]
command = "npx"
args = ["-y", "@clocknext/mcp"]

[mcp_servers.mcp.env]
CLOCKNEXT_API_KEY = "<YOUR_CLOCKNEXT_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' mcp npx -- -y @clocknext/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@clocknext/mcp"
      ],
      "env": {
        "CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `CLOCKNEXT_API_KEY` | yes | yes | Your organisation's cnk_… API key (Settings → API Keys). |
| `CLOCKNEXT_BASE_URL` | no | no | Override the API origin (e.g. a staging URL). Defaults to production. |
| `CLOCKNEXT_DOCS_URL` | no | no | Override the docs origin for the search_docs/get_doc tools. Defaults to https://help.clocknext.com. |

## Tools (5)

- `clocknext_whoami`
- `clocknext_list_models`
- `clocknext_add_model`
- `clocknext_get_customer_balances`
- `clocknext_get_customer_plan`

## FAQ

### What is required to use the Clocknext tools?

A Clocknext API key starting with `cnk_` is required and should be stored in your server's environment variables.

### Does the MCP server track or meter usage itself?

No, the MCP server is used to configure billing and manage plans, but actual usage metering is handled by your product's code via the Clocknext SDK.

### Which AI agents support the Clocknext skill?

The skill works with almost every major agent including Claude Code, Cursor, Codex, Windsurf, Gemini, Antigravity, and VS Code.
