# Clocknext

> Clocknext is an MCP server for finance and payments. MCP server that lets AI coding tools meter usage and manage usage-based billing. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Platforms:** CLI, VS Code, API, macOS, Linux, Windows
- **Repository:** https://github.com/clocknext/clocknext-mcp
- **MCP Registry name:** io.github.Clocknext/mcp
- **Categories:** [finance and payments](https://ai-powered.com/categories/finance-and-payments)
- **Listing updated:** 2026-11-21

## About

The README describes this server as a local stdio process that an AI coding tool launches as a subprocess, keeping the organisation's ClockNext API key in the server environment rather than in the model's context. Its tools cover checking which organisation and mode a key belongs to, listing enabled models with per-token USD prices, enabling catalogue models, and reading a customer's balances and active plan.

The server configures billing but does not record usage itself. The README is explicit that real usage signals come from the product's own code through the separate @clocknext/sdk, and the onboarding skill in the same repo walks through testing that integration with a dummy customer before going live.

It suits developers and teams who already use a Claude Code, Cursor, Codex or similar client and want their agent to set up or inspect usage-based billing with ClockNext.

## Features

- **Local stdio transport:** Runs as a subprocess launched by the AI client, with the API key kept in the server's environment.
- **Organisation and mode check:** A whoami tool reports which organisation a key belongs to and whether it is sandbox or live.
- **Model catalogue access:** Lists enabled models with USD prices per million tokens and can enable catalogue models.
- **Customer balance and plan lookup:** Reads a customer's wallet, credit, outcome and unit balances and their current active plan.
- **Documentation search:** Search and fetch ClockNext docs through dedicated tools, with a configurable docs origin.

## Good for

- Setting up usage-based billing for a product from inside an AI coding assistant
- Checking that the models and agent keys in code resolve to enabled ClockNext catalogue entries
- Inspecting a customer's current plan and balances during integration testing
- Looking up ClockNext documentation without leaving the coding session

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

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

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

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

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `clocknext_whoami`: Identifies the org behind the key and whether it is sandbox or live.
- `clocknext_list_models`: Lists enabled models and USD prices per 1M tokens.
- `clocknext_add_model`: Enables a catalog model.
- `clocknext_get_customer_balances`: Returns a customer's wallet, credit, outcome and unit balances.
- `clocknext_get_customer_plan`: Returns a customer's current active plan.

## FAQ

### Does the MCP server record usage?

No. The README says it configures billing but never meters it; real signals are sent from the product's code through the SDK.

### What is needed to run Clocknext?

A ClockNext API key in the CLOCKNEXT_API_KEY environment variable, obtained from Settings → API Keys.

### Which clients does Clocknext work with?

The README lists Claude Code, Cursor, Codex, Windsurf, VS Code, Gemini CLI and other MCP clients, launched with npx -y @clocknext/mcp.

### How do I add Clocknext to Claude Code?

Run this command in your terminal: claude mcp add mcp --env CLOCKNEXT_API_KEY='<CLOCKNEXT_API_KEY>' -- npx -y @clocknext/mcp

### What are the best alternatives to Clocknext?

The closest alternatives to Clocknext are Clocknext-Inc, Paas Build MCP and Klap.

## Where this comes from

- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Clocknext-Inc](https://ai-powered.com/mcp/clocknext-inc): Clocknext-Inc is an MCP server for finance and payments.
- [Paas Build MCP](https://ai-powered.com/mcp/paas-build-mcp): Paas Build MCP is a paid MCP server for finance and payments.
- [Klap](https://ai-powered.com/mcp/klap-2): Klap is an open-source MCP server for finance and payments.

---
Source: https://ai-powered.com/mcp/clocknext-2
