Securely connect your favorite AI agent directly to your Clockify account to help you track time, pull reports, and audit timesheets.

Security and permissions

• The AI agent inherits your exact Clockify user permissions
• The AI agent can only read data or log time for projects you already have access to

Generar clave API #

You’ll be connecting your AI agent to Clockify using your API key.

To generate your personal API key: 

1. Inicia sesión en tu cuenta Clockify
2. Click on your photo on the top-right corner
3. Selecciona: Preferencias
4. Haz clic en Avanzado pestaña
5. Haz clic en Gestionar claves API
6. Selecciona: Generate New

Connect Clockify MCP to Gemini CLI #

When you have obtained your API key, you can connect it to your Gemini CLI.

1. Locate your settings.json file, which is normally located in your user root directory inside the hidden .gemini folder (cd ~/.gemini/).
   
   Nota: On macOS, you can press CMD+SHIFT+G and type this path to open the directory directly.
   
2. Open the settings.json file and add the following code:

{
"mcpServers": {
  "posts-api-mcp": {
    "httpUrl": "https://mcp-server.stage.ops.clockify.me/mcp-server/mcp",
    "headers": {
      "x-api-key": "API_KEY"
    }
  }
}

3. Replace API_KEY with the API key generated from your workspace.

Restart Gemini to start using the Clockify MCP server.

Or you can use the following command:

gemini mcp add --transport http --header "x-api-key: API_KEY" posts-api-mcp https://mcp-server.stage.ops.clockify.me/mcp-server/mcp

Replace API_KEY with the API key generated from your workspace.

Connect Clockify MCP to Claude CLI #

If you are using Claude CLI, you can also connect it to the Clockify MCP server. To do this, paste the code below into your .mcp.json file:

{
  "mcpServers": {
    "clockify-mcp": {
      "type": "http",
      "url": "https://mcp-server.stage.ops.clockify.me/mcp-server/mcp",
      "headers": {
        "x-api-key": "API_KEY"
      }
    }
  }
}

Or, you can use the following command:

claude mcp add clockify-mcp https://mcp-server.stage.ops.clockify.me/mcp-server/mcp --transport http --header "x-api-key: API_KEY"

Replace API_KEY with the API key generated from your workspace.

Connect Clockify MCP to Codex CLI #

The Clockify MCP server can also connect to the Codex CLI. To do this, simply paste the code below into your config.toml file:

[mcp_servers.clockify-mcp]
transport = "http"
url = "https://mcp-server.stage.ops.clockify.me/mcp-server/mcp"
http_headers = { "x-api-key" = "API_KEY" }

Replace API_KEY with the API key generated from your workspace.

Qué puedes hacer #

The available tools and actions depend on your existing Clockify Role-Based Access Control (RBAC) permissions. These are all the available tools that the Clockify MCP server lets you use:

Tools are the core actions the AI agent can perform for you in Clockify:

Tool	Descripción
iniciar el temporizador	Start a timer naturally. You can also backdate timers, log “Breaks” (if enabled in your workspace), or ask the AI agent to attach available Custom Fields in your workspace such as mileage, expenses, location, or department.
stop timer	Stop your current timer. You can also ask the AI agent to add missing details as you stop it.
log past time	Log historical time. You can give the AI agent a simple duration, ask it to split time across a full day, or give it a sequence of tasks to stack back-to-back starting from your morning clock-in.
update time entry	Fix mistakes in your past logs. Just tell the AI agent what needs changing and it will find the entry and update the project, task, tag, or description.
bulk update time entries	Make massive changes instantly without slowing down. You can say, “Mark all my entries from yesterday as billable,” and the AI agent will update them all at once.
list time entries	The AI agent uses this to understand conversational references like “the entry from yesterday morning” so you don’t have to look up exact dates or IDs.
create client / project / task / tag	Create new workspace items on the fly just by asking the AI agent to set them up.
get current timer	Ask the AI agent what you are currently working on to get a quick status update.
list custom fields	The AI agent uses this to check which custom fields (like expenses or drop-downs) are available in your workspace so it applies them accurately.
list clients / projects / tasks / tags	The AI agent searches these lists to instantly recognize the names of the things you are working on.
get summary report	Ask conversational questions about your time (“Show me billable hours for the last 6 months” o “How much time went to the Apollo project in Q3?”), and the AI agent will calculate the dates and pull the exact totals.
get detailed report	Fetch a granular list of individual time entries to audit specific historical tasks.
generate attendance report	Check your exact daily, weekly, or monthly capacity, including precise overtime and undertime calculations (Requires a Pro plan).

Available prompts (Pre-built workflows) #

Prompts are smart, multi-step routines the AI agent can run to analyze your work by using your historical time entries to generate reports, audit your timesheets, and assess productivity. 

For example, you can run the productivity pattern audit prompt to analyze your chronological time entries from the last month to see when you are most focused.

Prompt	Descripción
generate daily standup	Formats a professional, copy-pasteable summary of the previous workday’s tracked hours for your team chats.
audit timesheet	Scans recent logs to find common anomalies like missing metadata (projects, clients, tags, and description), unlogged days, or accidentally left-on timers.
client billing summary	Generates a polished breakdown of hours distributed across a client’s projects.
project burn rate analyzer	Compares actual time tracked against a project’s original estimate to see if you are on track or over budget.
team utilization audit	Reviews a team’s utilization rates, calculating the billable efficiency for each member and comparing it to the expected target goal.
productivity pattern audit	Analyzes chronological time entries to measure context-switching, deep work intervals, and overall daily rhythm.

Available resources #

The AI agent silently reads following resources in the background so it never has to ask you same setup questions:

• user profile: Gives the AI agent your identity, workspace settings, local timezone, default workday start time, daily capacity, and which day your work week starts on. 
• recent time entries: Supplies a historical log of your recent time entries so the AI agent understands your current context and habits.

Glossary #

• Actions: The specific operations or commands executed by the AI agent to manage your Clockify data, such as logging time, updating entries, or fetching reports.
  
• AI agent: An artificial intelligence system (accessed via Gemini, Claude, or Codex CLI) that securely connects to your workspace to track time, analyze data, and execute tasks conversationally.

• API Key: A unique security token generated within your Clockify account preferences, used to authenticate and authorize the AI agent’s access to your workspace.
  
• CLI (Command Line Interface): The text-based terminal environment (e.g., Gemini CLI, Claude CLI, Codex CLI) where you configure the settings to connect your AI agent to the MCP server.
  
• Custom Fields: Additional categorizations within your Clockify workspace (such as mileage, expenses, location, or department) that the AI agent can automatically attach to your time entries.
  
• MCP (Model Context Protocol) Server: The secure integration bridge that enables your AI agent to read context and safely execute actions within your Clockify account.
  
• Prompts (Pre-built Workflows): Smart, multi-step analytical routines the AI agent can run on your behalf, such as auditing timesheets, generating standup reports, or analyzing productivity patterns.
  
• RBAC (Role-Based Access Control): The security framework in Clockify that determines exactly which projects and permissions your AI agent inherits when interacting with your workspace.
  
• Resources: Background data such as your user profile, local timezone, daily capacity, and recent time entries that the AI agent silently reads to contextualize your requests without requiring manual setup.
  
• Tools: The core, built-in functions the AI agent uses to interact with Clockify, ranging from starting and stopping timers to generating detailed billing and attendance reports.