Ermöglicht es AI Agents, die Nutzung zu messen, Signale zu verifizieren und die nutzungsbasierte Abrechnung über die Clocknext API zu verwalten.
Auch bekannt als ClockNext/clocknext-mcp, clocknext-mcp, @clocknext/mcp
- Stars
- 0
- Tools
- 5
- Downloads, 30 Tage
- 1.177
- Neueste Version
- 0.6.0
- Letzter Commit
- 13. Nov. 2026
- Lizenz
- —
Was ist Clocknext MCP?
Clocknext ist ein MCP server. Ermöglicht es AI Agents, die Nutzung zu messen, Signale zu verifizieren und die nutzungsbasierte Abrechnung über die Clocknext API zu verwalten. Er stellt 5 Tools bereit, etwa clocknext_whoami, clocknext_list_models, clocknext_add_model.
Zusammenfassung generiert aus dem README des Projekts
Über Clocknext MCP server
Dieser Server ermöglicht es dir, nutzungsbasierte Abrechnungen zu verwalten und Signale direkt aus deiner AI Coding Umgebung heraus zu verifizieren. Entwickler können die Nutzung messen, Kunden-Guthaben prüfen und Preismodelle über die Clocknext API verwalten. Der Server läuft lokal über stdio als Subprocess, sodass der API Key deiner Organisation sicher in deiner Umgebung bleibt und nicht an das Modell übertragen wird.
Entwickler können dies mit einer Vielzahl von MCP Clients nutzen, darunter Claude Code, Cursor, Windsurf und VS Code. Während der Server die Kern-Tools bereitstellt, enthält er auch einen geführten Onboarding Skill, der den Setup-Prozess von der Modell-Erkennung bis zum Testen mit Dummy-Kunden automatisiert. Für Claude Code Nutzer ist ein spezielles Plugin verfügbar, um sowohl den Server als auch den Onboarding Skill in einem einzigen Schritt zu installieren.
Zu den spezifischen Tools, die dem Agent zur Verfügung stehen, gehören clocknext_whoami zur Identifizierung deiner Organisation, clocknext_list_models zur Ansicht der Preise pro Million Tokens und clocknext_get_customer_balances zur Prüfung des Wallet- oder Credit-Status. Die Konfiguration des Servers erfolgt über die Umgebungsvariable CLOCKNEXT_API_KEY.
Was du damit machen kannst
- 1Automatisierte Billing-EinrichtungNutze den geführten Onboarding Skill, um Modelle zu erkennen, Berechtigungen festzulegen und die Nutzung mit einem Dummy-Kunden zu testen.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du Clocknext MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügenClocknext MCP in Claude Code installieren
$ claude mcp add --env 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' clocknext-mcp -- npx -y @clocknext/mcpClocknext MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"clocknext-mcp": {
"command": "npx",
"args": [
"-y",
"@clocknext/mcp"
],
"env": {
"CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
}
}
}
}Clocknext MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"clocknext-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@clocknext/mcp"
],
"env": {
"CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
}
}
}
}Clocknext MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"clocknext-mcp","type":"stdio","command":"npx","args":["-y","@clocknext/mcp"],"env":{"CLOCKNEXT_API_KEY":"<YOUR_CLOCKNEXT_API_KEY>"}}'Clocknext MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"clocknext-mcp": {
"command": "npx",
"args": [
"-y",
"@clocknext/mcp"
],
"env": {
"CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
}
}
}
}Clocknext MCP in Codex installieren
$ codex mcp add clocknext-mcp --env 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' -- npx -y @clocknext/mcpClocknext MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.clocknext-mcp] command = "npx" args = ["-y", "@clocknext/mcp"] [mcp_servers.clocknext-mcp.env] CLOCKNEXT_API_KEY = "<YOUR_CLOCKNEXT_API_KEY>"
Clocknext MCP in Gemini CLI installieren
$ gemini mcp add -s user -e 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' clocknext-mcp npx -- -y @clocknext/mcpClocknext MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"clocknext-mcp": {
"command": "npx",
"args": [
"-y",
"@clocknext/mcp"
],
"env": {
"CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
}
}
}
}Clocknext MCP tools 5
Erkannt aus dem READMEclocknext_whoamiclocknext_list_modelsclocknext_add_modelclocknext_get_customer_balancesclocknext_get_customer_plan
| clocknext_whoami | — | |
| clocknext_list_models | — | |
| clocknext_add_model | — | |
| clocknext_get_customer_balances | — | |
| clocknext_get_customer_plan | — |
Konfiguration
CLOCKNEXT_API_KEYErforderlichSecretYour organisation's cnk_… API key (Settings → API Keys).
CLOCKNEXT_BASE_URLOverride the API origin (e.g. a staging URL). Defaults to production.
CLOCKNEXT_DOCS_URLOverride the docs origin for the search_docs/get_doc tools. Defaults to https://help.clocknext.com.
| Name | Beschreibung | Typ |
|---|---|---|
| CLOCKNEXT_API_KEY | Your organisation's cnk_… API key (Settings → API Keys). | ErforderlichSecret |
| CLOCKNEXT_BASE_URL | Override the API origin (e.g. a staging URL). Defaults to production. | |
| CLOCKNEXT_DOCS_URL | Override the docs origin for the search_docs/get_doc tools. Defaults to https://help.clocknext.com. |
Automatisierte Checks
Geluften am 14. Nov. 2026Vollständiger Bericht →Unsere automatisierten Checks bestanden. Das ist kein Security-Audit: Lies den Code und gib dem Server nur den minimal notwendigen Zugriff. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbarclocknext/clocknext-mcp is public and reachablegithub.com/clocknext/clocknext-mcp ↗Bestanden
- Paket nennt dieses Repository als QuelleNicht geprüft
- Build-Provenienz (Sigstore-Attestierung)No build attestation published for this releaseNicht geprüft
- Open Source Lizenz (OSI)No licenseBefund
- Commit oder Release im letzten JahrLast commit or release 2026-11-13github.com/clocknext/clocknext-mcp ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNo popular package one edit away from @clocknext/mcpBestanden
- Keine kritischen Advisories im Paket oder seinen Abhängigkeiten1 resolved dependencies checked; no critical advisoryosv.dev ↗Bestanden
- Keine versteckten Anweisungen an das Modell5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNo tool named like delete, drop or execBestanden
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehen@clocknext/mcp
The Clocknext MCP server — meter usage, verify signals, and manage usage‑based billing directly from AI coding tools (Claude Code, Cursor, Codex, Antigravity, …) and any other Model Context Protocol client.
It runs locally over stdio: your AI tool spawns it as a subprocess, and your
organisation's cnk_… API key stays in the server's environment — never in the
model's context.
This repo ships two things:
- the MCP server (
@clocknext/mcp) — the tools an agent calls. - the
clocknext-onboardingskill — the step‑by‑step playbook that drives a full setup using those tools (human‑in‑the‑loop, sandbox‑first).
Install them together (the Claude Code plugin) or separately. Pick by what you want and which agent you're on:
| Install | What you get | Works in |
|---|---|---|
Skill — npx skills add Clocknext-Inc/clocknext-mcp |
the guided onboarding flow | every agent (Claude Code, Cursor, Codex, Windsurf, Gemini, Antigravity, VS Code, …) |
MCP server — npx -y @clocknext/mcp |
the tools an agent calls | every MCP client |
Plugin — /plugin install clocknext@clocknext |
MCP tools + skill, one step | Claude Code only |
The skill and the MCP server work together — the skill drives the tools — so for the full guided experience install both (or just use the plugin, which bundles them). The plugin is the one‑command option, but Claude Code only.
A Clocknext API key is required for the tools: Settings → API Keys →
cnk_…. It is a server‑side secret — keep it in env/secret config, never in client code or a repo.
1 — The skill (every AI coding agent)
The clocknext-onboarding skill is the guided playbook (detect models →
entitlements → plan → meter the codebase → test with a dummy customer). It
drives the MCP tools, so install the MCP server too (§2 below) — the skill
on its own has nothing to call.
Install it with npx skills — one command, works
across Claude Code, Cursor, Codex, Windsurf, Gemini, Antigravity, VS Code, and
~20 other agents. Target your agent with --agent so it lands where that
agent actually looks:
# user-wide (all projects), for a specific agent:
npx skills add Clocknext-Inc/clocknext-mcp --global --agent claude-code
# …or this project only:
npx skills add Clocknext-Inc/clocknext-mcp --agent claude-code
Swap claude-code for cursor, codex, windsurf, … (or * for every
detected agent). npx skills list shows what's installed;
npx skills remove clocknext-onboarding removes it. After installing, restart
the agent — most load skills at startup.
Claude Code, read this. Claude Code only loads skills from
~/.claude/skills/,.claude/skills/, or a plugin — not the CLI's default universal.agents/skills/folder. So you must pass--agent claude-code(as above), which installs to~/.claude/skills/(with--global) or.claude/skills/. A barenpx skills add …puts it in.agents/skills/, where Claude Code will never see it. Simplest of all for Claude Code: use the plugin — it registers the skill natively and wires the MCP in one step.
Copy the folder from the repo into your agent's skills directory:
git clone https://github.com/Clocknext-Inc/clocknext-mcp
# Claude Code — all projects:
mkdir -p ~/.claude/skills && cp -r clocknext-mcp/skills/clocknext-onboarding ~/.claude/skills/
# …or this project only: .claude/skills/
For tools without a native skills folder (Cursor / Windsurf / Codex / Antigravity),
point their rules file at skills/clocknext-onboarding/SKILL.md — e.g.
.cursor/rules/clocknext-onboarding.md, Windsurf Rules, or AGENTS.md. Keep the
references/*.md files alongside SKILL.md.
2 — The MCP server (every AI coding agent)
Gives you the tools the skill (and you) call — one stdio server,
npx -y @clocknext/mcp, with your CLOCKNEXT_API_KEY in its env.
Most clients take the standard block below — same JSON, they just differ on the file it goes in:
{
"mcpServers": {
"clocknext": {
"command": "npx",
"args": ["-y", "@clocknext/mcp"],
"env": { "CLOCKNEXT_API_KEY": "cnk_your_key" }
}
}
}
CLI agents
Claude Code — one command:
claude mcp add clocknext --env CLOCKNEXT_API_KEY=cnk_your_key -- npx -y @clocknext/mcp
Gemini CLI — ~/.gemini/settings.json → the standard block.
Codex — ~/.codex/config.toml:
[mcp_servers.clocknext]
command = "npx"
args = ["-y", "@clocknext/mcp"]
env = { CLOCKNEXT_API_KEY = "cnk_your_key" }
GitHub Copilot CLI — copilot mcp add, or ~/.copilot/mcp-config.json:
{
"mcpServers": {
"clocknext": {
"type": "local",
"command": "npx",
"args": ["-y", "@clocknext/mcp"],
"env": { "CLOCKNEXT_API_KEY": "cnk_your_key" },
"tools": ["*"]
}
}
}
OpenCode — ~/.config/opencode/opencode.json (note: mcp root, command
is an array, env is environment):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"clocknext": {
"type": "local",
"command": ["npx", "-y", "@clocknext/mcp"],
"environment": { "CLOCKNEXT_API_KEY": "cnk_your_key" },
"enabled": true
}
}
}
Factory (Droid) — droid mcp add, or the standard block in its config
with "type": "stdio" added to the server:
droid mcp add --type stdio clocknext "npx -y @clocknext/mcp"
Kimi Code — kimi mcp add clocknext -- npx -y @clocknext/mcp (set
CLOCKNEXT_API_KEY in the environment; config lives in ~/.kimi/config.toml).
IDEs
Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) → the
standard block.
Windsurf — ~/.codeium/windsurf/mcp_config.json → the standard block.
Antigravity — its MCP settings JSON → the standard block.
Kiro — .kiro/settings/mcp.json (project) or ~/.kiro/settings/mcp.json
(user) → the standard block. Kiro doesn't inherit your shell PATH, so if
npx isn't found, use its full path (which npx).
VS Code (native MCP / Copilot) — .vscode/mcp.json (uses servers, not
mcpServers):
{
"servers": {
"clocknext": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@clocknext/mcp"],
"env": { "CLOCKNEXT_API_KEY": "cnk_your_key" }
}
}
}
Any other MCP client — point it at the stdio command npx -y @clocknext/mcp
with CLOCKNEXT_API_KEY in env. @clocknext/mcp is also in the official
MCP Registry as
io.github.Clocknext-Inc/mcp, so registry‑aware clients can discover it directly.
(The older entry io.github.Clocknext/mcp stops at 0.13.0: the GitHub
organisation was renamed to Clocknext-Inc, and the registry only lets it publish
under its own name.)
Environment
| Variable | Required | Description |
|---|---|---|
CLOCKNEXT_API_KEY |
yes | Your org's cnk_… key (Settings → API Keys). |
CLOCKNEXT_BASE_URL |
no | Override the API origin (e.g. a staging URL). Defaults to production. |
CLOCKNEXT_DOCS_URL |
no | Override the docs origin for the search_docs/get_doc tools. Defaults to https://help.clocknext.com. |
3 — The Claude Code plugin (Claude Code only)
The one‑command option — installs the MCP server and the clocknext-onboarding
skill together, and wires the API key for you. Claude Code only (the plugin
format is Claude Code's; other agents use §1 + §2 above).
/plugin marketplace add Clocknext-Inc/clocknext-mcp
/plugin install clocknext@clocknext
Claude Code prompts for your Clocknext API key at install (stored securely), runs
the bundled server, and auto‑discovers the skill from the plugin's skills/
folder. Verify:
/mcp→ theclocknexttools are listed.- The skill triggers automatically when you start any Clocknext work (or check your installed skills).
No manual config, no env vars, nothing to build.
Tools
| Tool | What it does |
|---|---|
clocknext_whoami |
Identify the org behind the key and whether it's sandbox or live. Call first. |
clocknext_list_models |
List enabled models + USD prices per 1M tokens. Use a modelId in signals. |
clocknext_add_model |
Enable a catalog model (autopriced); warns if it has no catalog price. |
clocknext_get_customer_balances |
A customer's current wallet / credit / outcome / unit balances. |
clocknext_get_customer_plan |
A customer's current active plan (from their purchase). |
Plus catalogue CRUD (create_plan / create_credit / create_outcome /
create_unit …), customer tools (create_customer, create_purchase,
bulk_import_customers), and the docs tools (search_docs, get_doc). Run
/mcp to see the full list.
A typical agent flow: whoami → list_models → get_customer_plan (confirm
the plan, and that every model and agent key the code will send resolves) → run
the product's own code so it fires a real signal through @clocknext/sdk →
the SDK's signals.usageLog({ customerId }) (confirm it landed). The clocknext-onboarding skill
orchestrates all of this.
The MCP configures billing but never meters it. There is no record/track
tool by design, and no preview either: real signals come from your product's
code via the SDK (signals.credit / .wallet / .outcome), which is also the
only thing that proves the integration end-to-end. The SDK's signals.usageLog()
is the proof one landed; the MCP has no usage-read tool.
Development
npm install
npm run build # tsup → dist/index.js (executable bin)
npm run dev # run from source via tsx
CLOCKNEXT_API_KEY=cnk_... npm start
Built on the official @modelcontextprotocol/sdk, with its own small fetch
client for the Clocknext API (src/api.ts), all bundled into dist/ by tsup. stdio today; a hosted Streamable‑HTTP variant is planned.
Logs go to stderr (stdout is the protocol channel). The committed dist/ is
what the plugin runs — rebuild and commit it on any code change.
Releasing (maintainers) — automated
A tag push publishes both the npm package and the official MCP Registry entry,
via .github/workflows/publish-mcp.yml:
# 1. bump the version in package.json, server.json (both "version" fields),
# src/index.ts and .claude-plugin/plugin.json; rebuild + commit:
npm run build && git commit -am "release: vX.Y.Z"
# 2. tag and push — CI does the rest:
git tag vX.Y.Z && git push origin main --tags
The workflow checks the tag matches package.json, builds, npm publishes (with
provenance), then authenticates to the registry with GitHub OIDC (no secret)
and publishes server.json. It hosts only metadata pointing at the npm package,
so the npm publish runs first.
One‑time setup: add an NPM_TOKEN secret (repo → Settings → Secrets → Actions).
To drop the token entirely, configure npm trusted publishing (OIDC) for
@clocknext/mcp on npmjs.com and delete the NODE_AUTH_TOKEN line.
npm publish --access public # npm first — the registry validates against it
# get the publisher CLI (Linux/macOS, no brew needed):
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
./mcp-publisher login github # device flow — must be a Clocknext org member
./mcp-publisher publish # reads server.json (name io.github.Clocknext-Inc/mcp)
See the MCP Registry docs.
Clocknext MCP Fragen
Wie füge ich Clocknext MCP zu Claude Code hinzu?
Führe claude mcp add --env 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' clocknext-mcp -- npx -y @clocknext/mcp in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich Clocknext MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Welche Tools bietet Clocknext MCP?
Er stellt 5 Tools bereit, darunter clocknext_whoami, clocknext_list_models, clocknext_add_model, clocknext_get_customer_balances, clocknext_get_customer_plan.
Was ist erforderlich, um die Clocknext Tools zu nutzen?
Ein Clocknext API Key, der mit cnk_ beginnt, ist erforderlich und sollte in den Umgebungsvariablen deines Servers gespeichert werden.
Trackt oder misst der MCP server die Nutzung selbst?
Nein, der MCP server wird verwendet, um das Billing zu konfigurieren und Plans zu verwalten, aber die eigentliche Messung der Nutzung erfolgt über den Code deines Produkts via Clocknext SDK.