AI 코딩 에이전트 및 MCP 클라이언트에서 AI 도구의 사용량을 측정하고 사용량 기반 과금 체계를 직접 관리합니다.
다른 이름 Clocknext/clocknext-mcp, @clocknext/mcp
- 스타
- 0
- Tools
- 5
- 다운로드, 30일
- 1,177
- 최신 버전
- 0.13.0
- 마지막 커밋
- 2026년 11월 13일
- 라이선스
- —
Clocknext MCP란?
Clocknext은(는) MCP server입니다. AI 코딩 에이전트 및 MCP 클라이언트에서 AI 도구의 사용량을 측정하고 사용량 기반 과금 체계를 직접 관리합니다. 5개 도구를 제공합니다. 예: clocknext_whoami, clocknext_list_models, clocknext_add_model.
프로젝트 README에서 생성된 요약
Clocknext MCP server 정보
이 MCP server를 통해 개발자는 AI 도구의 사용량 기반 과금 및 측정을 관리할 수 있습니다. Claude Code, Cursor, Windsurf와 같은 AI 코딩 에이전트에서 모델 가격 모니터링, 고객 잔액 확인, 구독 플랜 관리를 직접 수행할 수 있습니다. 서버는 subprocess로서 stdio를 통해 로컬에서 실행되므로, 조직의 API key가 모델 컨텍스트에 노출되지 않고 서버 환경에 안전하게 유지됩니다.
도구를 사용하려면 cnk_ 접두사로 시작하는 Clocknext API key를 제공해야 합니다. 이 패키지에는 모델 감지, 권한 설정, 더미 고객을 통한 테스트 과정을 안내하는 전용 온보딩 skill이 포함되어 있습니다. MCP server는 clocknext_list_models 및 clocknext_get_customer_balances와 같은 기본 도구를 제공하며, 온보딩 skill은 이러한 작업들을 구조화된 워크플로우로 조율합니다. 이 설정은 Gemini, Codex, GitHub Copilot CLI를 포함한 다양한 클라이언트와 호환됩니다.
활용 사례
- 1온보딩 워크플로우 자동화가이드된 플레이북에 따라 모델과 플랜을 설정하고 코드베이스의 사용량을 측정합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Clocknext MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Clocknext MCP 설치
$ claude mcp add --env 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' mcp -- npx -y @clocknext/mcpCursor에 Clocknext MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@clocknext/mcp"
],
"env": {
"CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
}
}
}
}VS Code에 Clocknext MCP 설치
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@clocknext/mcp"
],
"env": {
"CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
}
}
}
}VS Code CLI에 Clocknext MCP 설치
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@clocknext/mcp"],"env":{"CLOCKNEXT_API_KEY":"<YOUR_CLOCKNEXT_API_KEY>"}}'Claude Desktop에 Clocknext MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@clocknext/mcp"
],
"env": {
"CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
}
}
}
}Codex에 Clocknext MCP 설치
$ codex mcp add mcp --env 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' -- npx -y @clocknext/mcpCodex config.toml에 Clocknext MCP 설치
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@clocknext/mcp"] [mcp_servers.mcp.env] CLOCKNEXT_API_KEY = "<YOUR_CLOCKNEXT_API_KEY>"
Gemini CLI에 Clocknext MCP 설치
$ gemini mcp add -s user -e 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' mcp npx -- -y @clocknext/mcpGemini settings.json에 Clocknext MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@clocknext/mcp"
],
"env": {
"CLOCKNEXT_API_KEY": "<YOUR_CLOCKNEXT_API_KEY>"
}
}
}
}Clocknext MCP 도구 5
README에서 감지됨clocknext_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 | — |
구성
CLOCKNEXT_API_KEY필수비밀Your 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.
| 이름 | 설명 | 유형 |
|---|---|---|
| CLOCKNEXT_API_KEY | Your organisation's cnk_… API key (Settings → API Keys). | 필수비밀 |
| 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. |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능clocknext/clocknext-mcp is public and reachablegithub.com/clocknext/clocknext-mcp ↗통과
- 패키지가 이 저장소를 소스로 명시@clocknext/mcp names clocknext/clocknext-mcp as sourcenpmjs.com/package/@clocknext/mcp ↗통과
- 빌드 출처(Sigstore 증명)Sigstore attestation for @clocknext/mcpnpmjs.com/package/@clocknext/mcp/v/0.13.0#provenance ↗통과
- 오픈 소스 라이선스 (OSI)No license결함 발견
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-13github.com/clocknext/clocknext-mcp ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from @clocknext/mcp통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음1 resolved dependencies checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음5 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기@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 질문
Clocknext MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --env 'CLOCKNEXT_API_KEY=<YOUR_CLOCKNEXT_API_KEY>' mcp -- npx -y @clocknext/mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Clocknext MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Clocknext MCP는 어떤 도구를 제공하나요?
5개 도구를 제공합니다. 예: clocknext_whoami, clocknext_list_models, clocknext_add_model, clocknext_get_customer_balances, clocknext_get_customer_plan.
Clocknext 도구를 사용하려면 무엇이 필요한가요?
cnk_로 시작하는 Clocknext API key가 필요하며, 이를 서버의 환경 변수에 저장해야 합니다.
MCP server가 직접 사용량을 추적하거나 측정하나요?
아니요, MCP server는 과금 설정 및 플랜 관리에 사용되며, 실제 사용량 측정은 Clocknext SDK를 통해 제품 코드에서 처리됩니다.
어떤 AI 에이전트가 Clocknext skill을 지원하나요?
이 skill은 Claude Code, Cursor, Codex, Windsurf, Gemini, Antigravity, VS Code를 포함한 거의 모든 주요 에이전트에서 작동합니다.