MCP Server Setup

The DevClocked MCP (Model Context Protocol) server lets AI assistants access your coding activity directly from their tool system. Ask about your hours, active sessions, weekly stats, and project breakdowns without leaving your assistant or terminal workflow.

What is MCP?

MCP is an open protocol that lets AI assistants connect to external tools and data sources. It is not just for Claude Code. Codex, Claude Code, Cursor, and other MCP-compatible clients can connect to MCP servers. By adding DevClocked as an MCP server, your assistant can query tracked time, sessions, projects, and weekly summaries in real time.

Prerequisites

• Node.js 18+ installed
• An MCP-compatible client such as Codex, Claude Code, or Cursor
• A DevClocked account with an API key

Step 1 - Authenticate

First, log in with your DevClocked API key. You only need to do this once per machine:

npx -y @devclocked/cli@latest login

When prompted, paste the API key from your DevClocked dashboard (Settings > API Keys). Your credentials are stored locally at ~/.config/devclocked/cli.json.

Step 2 - Register the MCP Server

Use the command for your assistant.

Codex

codex mcp add devclocked -- npx -y @devclocked/cli@latest mcp-server

Codex stores MCP server configuration in ~/.codex/config.toml by default. Start Codex and run /mcp to confirm the server is connected.

Claude Code

claude mcp add devclocked -- npx -y @devclocked/cli@latest mcp-server

Claude Code will start the DevClocked MCP server automatically when a session needs it. Inside Claude Code, run /mcp to inspect connected servers.

Other MCP Clients

For clients that use JSON or TOML configuration, register a local stdio server with command npx and arguments -y, @devclocked/cli@latest, and mcp-server.

Step 3 - Verify

Check that everything is connected:

npx -y @devclocked/cli@latest mcp-health

This checks auth, connectivity, and whether the MCP tools respond correctly.

Available Tools

Once connected, your assistant can use these tools to query your DevClocked data:

Tool	What it does
get_summary	Formatted text summary of today's coding activity
get_today_activity	Raw JSON for today's sessions, work blocks, repos, and token usage
get_active_session	Current active tracking session info
get_weekly_summary	Text summary of the past 7 days
get_weekly_summary_raw	Raw JSON data for the past 7 days
get_projects	Your projects with hours, sessions, commits, and active days

Example Usage

Once the MCP server is active, you can ask your assistant things like:

• "How many hours have I coded today?"
• "What's my weekly summary?"
• "Which project am I working on right now?"
• "Show me my activity breakdown for this week"
• "How many tokens have I used across projects today?"

The assistant can call the appropriate DevClocked MCP tool and present the results.

Alternative: Global Install

If you prefer installing globally instead of using npx:

npm install -g @devclocked/cli
devclocked login
codex mcp add devclocked -- devclocked mcp-server
claude mcp add devclocked -- devclocked mcp-server

Troubleshooting

"Not authenticated" error

Run npx -y @devclocked/cli@latest login and enter your API key. Check that ~/.config/devclocked/cli.json exists and contains valid credentials.

Health check failing

Run npx -y @devclocked/cli@latest mcp-health to diagnose. Common causes:

• Expired or revoked API key — generate a new one in Settings
• Network issues — check your internet connection
• Outdated CLI — run npx -y @devclocked/cli@latest mcp-health to use the latest version

MCP server not showing

Restart your assistant after adding the MCP server. In Codex and Claude Code, run /mcp to inspect the connected server list.