Quickstart

Chronova MCP Server — Quickstart

@chronova/mcp-server is a Model Context Protocol (MCP) server that exposes Chronova developer productivity data — coding stats, recent activity, and AI-assisted coding analytics — to AI agents such as Claude Desktop, Cursor, and OpenCode.

The package ships two transports:

• stdio (chronova-mcp-server bin) — for MCP clients that spawn a local process.
• HTTP / Streamable HTTP (dist/index.js) — a stateful Express server at /mcp, suited for remote/shared hosting and Docker.

See Architecture → Transports for the distinction.

Install

# Run directly via npx (stdio transport, the common path for MCP clients)
npx -y @chronova/mcp-server

# Or install globally
npm install -g @chronova/mcp-server
chronova-mcp-server

Configure the API key

The server needs a Chronova API key. It resolves configuration in priority order (highest first):

1. CHRONOVA_API_KEY environment variable
2. ~/.chronova.cfg — api_key as a top-level key
3. ~/.wakatime.cfg — api_key as a top-level key (WakaTime-compatible)
4. Default: empty — API requests will fail with 401 Unauthorized

api_url follows the same ladder (CHRONOVA_API_URL → config file → https://chronova.dev/api/v1). See Configuration for the full resolution rules and CLI flags.

Config files use INI-like syntax (section headers are ignored by the parser):

api_key = waka_your-api-key-here
api_url = https://chronova.dev/api/v1

Connect an AI client

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "chronova": {
      "command": "npx",
      "args": ["-y", "@chronova/mcp-server"],
      "env": { "CHRONOVA_API_KEY": "your-api-key" }
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "chronova": {
      "command": "npx",
      "args": ["-y", "@chronova/mcp-server"],
      "env": { "CHRONOVA_API_KEY": "your-api-key" }
    }
  }
}

OpenCode

opencode.json:

{
  "mcp": {
    "chronova": {
      "type": "local",
      "command": ["npx", "-y", "@chronova/mcp-server"],
      "enabled": true,
      "env": { "CHRONOVA_API_KEY": "your-api-key" }
    }
  }
}

Tools available to the agent

Once connected, the agent can call four read-only tools. See Tools reference for full parameter schemas.

Tool	Purpose	Required params
get_developer_context	User profile, subscription, GitHub status, org memberships	none
get_productivity_summary	Aggregated coding stats by time range	range
get_ai_insights	AI vs manual coding analytics	range
get_recent_activity	Paginated coding heartbeats with filters	none (all filters optional)

Named ranges: today, last_7_days, last_30_days, last_3_months, last_6_months, last_year, all_time. get_productivity_summary also accepts YYYY (year), YYYY-MM (month), and YYYY-MM-DD_to_YYYY-MM-DD (custom date range). get_ai_insights accepts named ranges and YYYY-MM-DD_to_YYYY-MM-DD.

Development

npm run dev          # tsc --watch + node --watch
npm test             # vitest run
npm run build        # tsc
npm run type-check   # tsc --noEmit
npm run lint         # eslint .

See Testing for the mock-based integration test harness and Operations for Docker and release details.