ClockifyMCP

Remote-first MCP server and ChatGPT app for personal Clockify time tracking.

ClockifyMCP exposes a small, review-friendly set of Clockify tools for ChatGPT and other MCP clients:

• Read profile, workspaces, projects, tasks, clients, tags, entries, current timer, and report summaries.
• Start/stop timers and create/update personal time entries.
• Delete personal time entries only with exact server-side confirmation.

The first release intentionally avoids team/admin/project management features to reduce permission and review risk.

Status

ClockifyMCP is a pre-deployment release candidate for a hosted remote MCP server. The tested core includes:

• Clockify REST client with pagination, retry, and error normalization.
• Encrypted Clockify API key storage primitives.
• Local OAuth access-token utilities, authorization-code + PKCE service, JWT jti, and persisted authorization-code/token revocation support.
• MCP tool descriptors, schema validation, and tool handlers.
• Fastify HTTP boundary for liveness/readiness, OAuth metadata, MCP server card, OAuth challenge, OAuth authorize/token/revoke routes, Clockify API-key onboarding UI/API, stored credential deletion, initialize, tools/list, and tools/call.
• Production app factory that wires Postgres credential storage, Postgres OAuth authorization-code and token revocation storage, OAuth service, and Clockify clients from environment variables.

The public deployment target is https://clockify.velryx.cc. Live MCP Inspector and ChatGPT developer-mode validation must still be captured after deployment.

Support: petylo.work+mcp@gmail.com Security: petylo.work+mcp@gmail.com Telegram: @edwy_reed

Development

npm install
npm test
npm run typecheck
npm run build
npm run readiness

Migration SQL lives in src/db/migrations/. Apply it to the production Postgres database before starting the hosted app.

Production OAuth authorization codes are stored in Postgres as short-lived, single-use records. This keeps ChatGPT account linking resilient across app restarts and multi-instance deployments.

Deployment details are documented in docs/deployment.md, including environment variables, migrations, HTTPS proxy requirements, and GET /healthz versus GET /readyz.

Marketplace validation and implementation standards are tracked in docs/standards-and-validation.md.

Run locally:

cp .env.example .env
# Replace CLOCKIFY_CREDENTIAL_ENCRYPTION_KEY and OAUTH_JWT_SECRET in .env.
# Apply src/db/migrations/001_oauth_credentials.sql to the Postgres database from .env.
npm run dev

npm run dev loads .env when it exists. PUBLIC_BASE_URL=http://localhost:3000 is accepted only for local loopback development; deployed ChatGPT/OAuth linking still requires a public HTTPS origin. The local runtime still requires a reachable Postgres database with migrations applied.

Generate a 32-byte encryption key:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Configuration

Required production environment:

• PUBLIC_BASE_URL: public HTTPS app origin. Local loopback development may use http://localhost:3000.
• TRUST_PROXY_HOPS: number of trusted reverse-proxy hops for client IP resolution, default 1 in production runtime.
• DATABASE_URL: production database connection.
• CLOCKIFY_CREDENTIAL_ENCRYPTION_KEY: 32-byte base64 key for encrypted Clockify API keys.
• CLOCKIFY_CREDENTIAL_ENCRYPTION_KEY_VERSION: active encryption key version.
• OAUTH_JWT_SECRET: signing secret for local OAuth access tokens.
• OAUTH_ALLOWED_REDIRECT_URIS: comma-separated allow-list for OAuth redirects.
• OAUTH_TOKEN_TTL_SECONDS: access-token lifetime.
• SENSITIVE_ROUTE_RATE_LIMIT_MAX: per-client limit for OAuth/onboarding POST attempts.
• SENSITIVE_ROUTE_RATE_LIMIT_WINDOW_MS: rate-limit window for OAuth/onboarding POST attempts.

For production ChatGPT app linking, add the redirect URI shown in Apps & Connectors, typically https://chatgpt.com/connector/oauth/{callback_id}, to OAUTH_ALLOWED_REDIRECT_URIS.

.env.example includes local sample values only. Never commit real Clockify API keys or OAuth secrets.

npm run readiness is a release gate for marketplace submission. It is expected to fail until live MCP Inspector evidence and ChatGPT developer-mode validation are recorded for the deployed endpoint.

Public ChatGPT submission is also blocked until the Clockify API-key onboarding policy gate in docs/marketplace-readiness.md is resolved. The current v1 flow asks users to enter a Clockify API key into ClockifyMCP, which must be explicitly accepted for public review or replaced with an approved Clockify authorization path.

Security Model

Clockify public API uses API keys. ChatGPT Apps account linking expects OAuth. ClockifyMCP therefore implements an OAuth wrapper:

1. User links ClockifyMCP through ChatGPT.
2. ChatGPT redirects the user to the ClockifyMCP onboarding UI.
3. User enters a Clockify API key in the ClockifyMCP onboarding UI.
4. The service validates the key with Clockify and stores only encrypted ciphertext plus non-secret metadata.
5. MCP tools use OAuth token subject + credential owner checks before decrypting credentials.

Clockify API keys are not scope-limited by Clockify, so v1 limits the exposed server-side tool surface to personal time tracking.

OAuth token exchange and Clockify API-key onboarding POST routes have an in-process rate limit. Keep an edge or platform rate limit in front of the public endpoint as well.

Users can disconnect stored Clockify credentials by calling DELETE /api/credential with a valid OAuth bearer token. The endpoint deletes all stored encrypted Clockify credentials for the token subject and returns a no-store response.

MCP Tools

V1 tools:

• get_clockify_profile
• search_clockify_entities
• list_time_entries
• get_current_timer
• start_timer
• stop_timer
• create_time_entry
• update_time_entry
• delete_time_entry
• summarize_time_report

Tool descriptors are defined in src/mcp/tools.ts; handlers are in src/mcp/handlers.ts.

Marketplace Checklist

Before submitting to ChatGPT or MCP catalogs:

• Deploy a stable public HTTPS endpoint.
• Configure deployment readiness probes against GET /readyz.
• Verify OAuth account linking in ChatGPT developer mode.
• Validate MCP with MCP Inspector.
• Capture screenshots and test prompts required by the OpenAI submission form.
• Publish privacy policy and terms at stable public URLs.
• Prepare demo Clockify account with sample data and no blocking 2FA/sign-up step.
• Verify organization permissions and OpenAI project eligibility in the dashboard.
• Run npm run readiness and resolve every reported blocker.

Distribution Plan

Primary:

• Public hosted remote MCP endpoint for ChatGPT Apps.
• GitHub repository as source of truth.
• Official MCP Registry metadata pointing to the remote endpoint.

Secondary:

• Smithery remote URL publishing.
• Glama connector metadata.
• Docker MCP Catalog after container hardening.

CAKE/Clockify Marketplace add-on support is a later track because it uses X-Addon-Token rather than the API-key OAuth wrapper used by v1.