Quick Start

npx timeforged-mcp

That's it. The server communicates over stdio using the Model Context Protocol.

Configuration

All configuration is done through environment variables:

| Variable | Description | Default | |---|---|---| | TF_API_KEY | Your TimeForged API key | (none) | | TF_SERVER_URL | TimeForged daemon URL | http://127.0.0.1:6175 |

Setup

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "timeforged": {
      "command": "npx",
      "args": ["-y", "timeforged-mcp"],
      "env": {
        "TF_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add timeforged \
  --transport stdio \
  --env TF_API_KEY=your-api-key \
  -- npx -y timeforged-mcp

Cursor / VS Code

Add to MCP settings:

{
  "mcpServers": {
    "timeforged": {
      "command": "npx",
      "args": ["-y", "timeforged-mcp"],
      "env": {
        "TF_API_KEY": "your-api-key"
      }
    }
  }
}

Tools

| Tool | Description | |---|---| | tf_status | Check daemon status (version, user/event counts) | | tf_today | Today's coding time with project & language breakdown | | tf_report | Time summary for any date range with filters | | tf_sessions | List coding sessions with durations | | tf_send | Send a manual heartbeat/event |

Examples

"How much did I code today?" → AI calls tf_today

"Show me last week's report for the timeforged project" → AI calls tf_report with from, to, project

"List my sessions from yesterday" → AI calls tf_sessions with from, to

Requirements

• Node.js >= 18
• Running TimeForged daemon

License

MIT