MCP · Streamable HTTP

Timex MCP — connect your AI to your day

Available from Timex 1.3.0.

What it is

Timex hosts a local MCP server over Streamable HTTP. It is off by default, bound to 127.0.0.1:41741 unless you change it, and protected by a bearer token.

For clients that launch stdio servers, Timex.app includes the timex-mcp bridge. Once connected, a client can see the activity Timex records, including window titles and URLs.

Enable it

  1. Open Settings ▸ Integrations.
  2. Turn on Enable MCP server.
  3. Copy the token.

If you change the host, Timex warns that the server may be reachable from your network. The bearer token is still required.

Connect a client

Replace YOUR_TOKEN with the token from Timex. Restart the client after changing its configuration.

Claude Code

Add Timex as a remote Streamable HTTP server.

claude mcp add --transport http timex http://127.0.0.1:41741/mcp --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop

Use Add to Claude Desktop in Settings ▸ Integrations, or add this to ~/Library/Application Support/Claude/claude_desktop_config.json.

{"mcpServers":{"timex":{"command":"/Applications/Timex.app/Contents/MacOS/timex-mcp"}}}

The bridge reads the host, port, and token from Timex preferences. TIMEX_MCP_URL and TIMEX_MCP_TOKEN override them. Alternatively, npx -y mcp-remote http://127.0.0.1:41741/mcp --header "Authorization: Bearer YOUR_TOKEN" works if Node is installed.

Codex CLI (OpenAI)

Export the token and use the CLI command, or add the TOML entry to ~/.codex/config.toml.

export TIMEX_MCP_TOKEN=YOUR_TOKEN
codex mcp add timex --url http://127.0.0.1:41741/mcp --bearer-token-env-var TIMEX_MCP_TOKEN
[mcp_servers.timex]
url = "http://127.0.0.1:41741/mcp"
http_headers = { Authorization = "Bearer YOUR_TOKEN" }

OpenCode

Add this remote server to opencode.json.

{"$schema":"https://opencode.ai/config.json","mcp":{"timex":{"type":"remote","url":"http://127.0.0.1:41741/mcp","enabled":true,"headers":{"Authorization":"Bearer YOUR_TOKEN"}}}}

Octomind by Muvon GitHub ↗

For Octomind with `headers` support (current master), add this HTTP server and reference it from the roles that should use it.

[[mcp.servers]]
name = "timex"
type = "http"
url = "http://127.0.0.1:41741/mcp"
headers = { Authorization = "Bearer YOUR_TOKEN" }
timeout_seconds = 30

# then add "timex" to server_refs of the roles that should use it:
# [roles.mcp]
# server_refs = ["core", "timex"]
url = "http://127.0.0.1:41741/mcp?token=YOUR_TOKEN"

For older Octomind builds that cannot send headers, use the fallback URL shown below. Timex accepts ?token= for header-less clients; keep it on loopback only.

Cursor

Save this in ~/.cursor/mcp.json.

{"mcpServers":{"timex":{"url":"http://127.0.0.1:41741/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}}}

Zed

Add this server entry to your Zed MCP settings.

{"mcpServers":{"timex":{"url":"http://127.0.0.1:41741/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}}}

VS Code

Save this in .vscode/mcp.json. VS Code uses the servers key instead of mcpServers.

{"servers":{"timex":{"url":"http://127.0.0.1:41741/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}}}

The 16 tools

get_summary

Summarize tracked time for a date range.

list_activities

List activity records for a date range.

search_activities

Search recorded apps, window titles, and URLs.

get_current_activity

Show what Timex is tracking right now.

list_categories

List categories and their focus weights.

list_rules

List app, title, and URL categorization rules.

add_rule

Create a categorization rule.

remove_rule

Delete a categorization rule.

create_category

Create a category with a focus weight.

update_category

Rename a category or change its weight.

add_manual_entry

Log time that was not tracked automatically.

export_csv

Export a date range to a CSV file.

pause_tracking

Pause automatic activity tracking.

resume_tracking

Resume automatic activity tracking.

start_break

Start a break in Timex.

list_backups

List the local Timex database backups.

Protocol: Streamable HTTP; protocol revisions 2026-07-28 / 2025-11-25 / 2025-06-18 / 2025-03-26; stateless (no sessions); ?token= is accepted for header-less clients; Origin is restricted to localhost.

Example prompts

  • “How much time in Zoom this week vs last?”
  • “What was I doing Tuesday between 2 and 4pm?”
  • “Make github.com count as Development”
  • “Log a 45-minute client call at 3pm today under Communication”
  • “Export this month as a CSV to ~/Desktop”

Troubleshooting

Timex is not running or its MCP server is disabled

Open Timex and enable the server in Settings ▸ Integrations.

401 Unauthorized

Regenerate or copy the token again, update the client configuration, and restart the client.

Bound to another host

The token is still required, and ?token= is still accepted. From browsers, the Origin check only allows localhost origins.