Using the MCP server with Timemator

Requirements#

• Timemator for Mac, version 3.4.0 or later.
• macOS 12 or later.
• The version from timemator.com and the version from Setapp work the same.
• Timemator must be running. The server is part of the app: it starts when Timemator starts and stops when you quit it.
• An MCP client on the same Mac that can connect to a server over HTTP.

The MCP server is in Beta. It works, but tool names and parameters may still change in a minor release of Timemator. Every change is listed in the reference's changelog.

The MCP server is only available on the Mac.

What is the MCP server?#

The Model Context Protocol (MCP) is the standard way for AI agents to use other apps. An app offers tools, small well-described actions, and the agent picks the tool that fits what you asked. Timemator's server offers 21 tools: the timer, folders and tasks, time entries, totals, export, the activity log, two that open Timemator's windows, and three that delete.

A few things you can ask an agent once it is connected:

• Log a meeting: "Log the 45-minute kick-off call with Acme at 10:00 today on Acme/Website."
• Start the timer for a ticket: "Start the timer on Acme/Website with the note TIM-43."
• Monthly total per client: "How many hours did I track for each client this month, and what's the revenue?"
• Export an invoice CSV: "Export October's unbilled Acme time as a CSV file to Downloads and mark it as billed."
• Clean up fragmented entries: "Yesterday's Design time is split into lots of short entries. Merge them into one."

The agent finds the task first, then makes the change. Every change to your folders, tasks and time entries can be undone in Timemator with Edit → Undo, and syncs to your other devices like a change you made yourself. Deleting activity records is the exception: as in the timeline, it cannot be undone.

The MCP Server Reference lists every tool with its parameters, results and examples. You do not need it to get started; your agent reads the same descriptions from the server.

Turn on the server#

The server is off until you switch it on.

1. Open Timemator → Preferences… and click Integrations.
2. Turn on the switch next to MCP Server.
3. The status line says Listening on http://127.0.0.1:2140/mcp. That address is what your client connects to.

The first time you switch the server on, Timemator creates a token, a long random password every client has to send. It is stored in your keychain and shown masked in the pane. Copy puts it on the clipboard.

Under Command for AI Agent, pick Claude Code, Codex or Cursor. The box shows the setup for that client with <TOKEN> in place of the token; the copy button in its corner puts it on the clipboard with your port and token filled in.

The port is 2140 unless you change it in the Port field (any number from 1024 to 65535). If you change it, change it in your client's configuration too.

Connect your agent#

Every client needs the same two things: the address http://127.0.0.1:2140/mcp (with your port), and the header Authorization: Bearer <token>. Always use 127.0.0.1, never localhost: see Security.

Codex#

Pick Codex under Command for AI Agent in Preferences → Integrations and click the copy button. You get two parts, each under a comment saying where it goes:

# Add this line to your shell profile (for example ~/.zshrc):
export TIMEMATOR_MCP_TOKEN=<token>

# Add this block to ~/.codex/config.toml:
[mcp_servers.timemator]
url = "http://127.0.0.1:2140/mcp"
bearer_token_env_var = "TIMEMATOR_MCP_TOKEN"

Codex reads the token from the environment variable TIMEMATOR_MCP_TOKEN, not from the file, so the export line is needed: open a new Terminal window after adding it, and start Codex from there. Instead of editing config.toml by hand, you can let Codex write the same block; the token still comes from the variable:

codex mcp add timemator --url http://127.0.0.1:2140/mcp --bearer-token-env-var TIMEMATOR_MCP_TOKEN

codex mcp list lists the server; in Codex, /mcp shows the connected servers.

Claude Code#

Pick Claude Code under Command for AI Agent, click the copy button and paste the command into Terminal:

claude mcp add --transport http timemator http://127.0.0.1:2140/mcp --header "Authorization: Bearer <token>"

This adds the server for the project folder you run it in. Add --scope user after add to have it in every project. claude mcp list shows whether it is connected; in Claude Code, /mcp shows its status and tools.

Cursor#

Add Timemator to ~/.cursor/mcp.json (for every project) or to .cursor/mcp.json in a project, with your token after Bearer . Pick Cursor under Command for AI Agent and click the copy button to get it with your port and token:

{
  "mcpServers": {
    "timemator": {
      "url": "http://127.0.0.1:2140/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Cursor can also read the token from an environment variable: write "Bearer ${env:TIMEMATOR_MCP_TOKEN}" instead. You switch MCP servers on and off under Customize in Cursor's sidebar. Cursor asks before it uses an MCP tool unless you allow it to run tools on its own.

Other clients#

Any client that supports MCP over HTTP ("Streamable HTTP") and lets you set a request header works: use the address and the Authorization header above. Timemator speaks the protocol revisions 2025-11-25, 2025-06-18 and 2025-03-26.

Security#

The server is built so that only clients you set up on this Mac can use it.

• It listens on this Mac only. The server accepts connections on 127.0.0.1, the Mac's internal address. Other computers on your network, and the internet, cannot reach it. Traffic never leaves the Mac, which is why it is plain HTTP.
• Every request needs the token. A request without it, or with a wrong one, is refused. The token keeps out programs that do not have it, other user accounts on the Mac included.
• Web pages are refused. A website you visit cannot drive your timer through the browser: requests that come from a browser are rejected, even with the right token.

What the token does not protect against:

• Software in your own account. The token sits in your client's configuration (or your shell profile, for Codex), where any program running as you can read it, as it could read your other files.
• What you let the agent do. A connected agent can do everything the tools allow, delete included. Timemator does not ask before a change: your client does. Most clients ask before every tool call, or at least before the destructive ones (the three deletes and merging time entries), so keep those prompts on unless you trust the agent. An export writes its file wherever the agent says, but it never replaces a file that is already there unless the agent asks for that explicitly (overwrite).
• Where your data goes. What a tool returns, such as task names, notes, totals or the activity log's window titles and websites, goes to the AI model your client uses, which usually runs in the cloud. Connect only clients you would trust with that.

If the token leaks, click Regenerate… in Preferences → Integrations. The old token stops working at once; copy the new one into the clients you still use.

Always 127.0.0.1, never localhost. Some clients look up localhost as the IPv6 address ::1 first, where Timemator does not listen, and then fail to connect. The address with 127.0.0.1 always works.

Read-only mode#

Reading never needs a license. Changing data does: when the trial has expired, Timemator is in read-only mode, and every tool that would change your data is refused with the code readOnlyMode. The agent can still read, show you things in Timemator, switch auto-tracking on or off, and export without marking entries as billed. get_status tells the agent whether Timemator is read-only. The Setapp version has no trial and is never read-only.

Troubleshooting#

The status line says "Could not start: Port 2140 is in use." Another app is using the port. Type another port into the Port field, such as 2141, press Return, and change the address in your client.

The client cannot connect, or reports "connection refused". Timemator is not running, or the server is off. Open Timemator and check that the status line says Listening on … with the port your client uses. If your agent should always reach Timemator, select Launch Timemator at login in Preferences → General.

The client reports 401 or "unauthorized". The token is missing or wrong, for example because it was regenerated. Copy it again from Preferences → Integrations. With Codex, check that echo $TIMEMATOR_MCP_TOKEN prints the token in the Terminal window you start Codex from.

The client reports 403 or "forbidden". The request came from a web browser, or used an address other than 127.0.0.1 or localhost with your port. Connect from an MCP client on the Mac, to http://127.0.0.1:<port>/mcp.

The client says the protocol version is not supported. Timemator speaks MCP revisions up to 2025-11-25. Update the client, or check whether it has a setting for an older revision.

A tool is refused. The agent gets a code and an English message that usually says what to do, as the text of the result, such as {"code":"taskArchived","message":"The task is archived, so the timer can't start on it. Pick another task or unarchive this one."}, and most agents act on it themselves. The codes are listed in the reference. If a tool does not do what the reference says, that is a bug; please write to support@timemator.com with what you asked and what happened.

Related#

• MCP Server Reference
• Using AppleScript with Timemator, for scripts, hotkeys and menu bar tools
• Model Context Protocol