Skip to content
English
  • There are no suggestions because the search field is empty.

Command Line: Connect Command-Line AI Tools to Time Doctor

Note: Available only with BETA CUSTOMERS for now.

The Time Doctor MCP is available on all Time Doctor plans and can be accessed by Owners, Admins, and Managers.

TL;DR: 

Sign in from Claude Code, Codex CLI, Gemini CLI, or Warp to connect to the Time Doctor MCP server. Each tool opens a browser window for sign-in the first time it connects. Tools that cannot open a browser, such as a server or a scheduled job, can connect instead with an API key.

 

Before Starting

  • A Time Doctor login with the Owner, Admin, or Manager role.
  • Time Doctor MCP enabled by an Owner or Admin in Settings / AI connections.
  • A terminal. On Windows, open the Start menu and search for PowerShell. On Mac, press Cmd and Space, then search for Terminal.
  • The desired tool is already installed and signed in.

The Time Doctor server URL is the same for every tool: https://api2.timedoctor.com/api/2.0/mcp/mcp

Each tool opens a browser window the first time it connects. Sign in with a Time Doctor login and click Allow access.

 

Claude Code

  1. Add the server:
    claude mcp add --transport http --scope user timedoctor https://api2.timedoctor.com/api/2.0/mcp/mcp

    About scope: user makes Time Doctor available in all projects. Use local for the current project only, or project to share it with a team through a checked-in config file.
  2. Sign in.
    Start Claude Code by typing claude, then run /mcp and follow the browser sign-in. Alternatively, run claude mcp login timedoctor.
  3. Confirm the connection.
    Run /mcp and look for Time Doctor marked as connected. Outside a session, claude mcp list shows the same information.

Claude Code stores the sign-in in the system keychain on Mac, or a credentials file elsewhere, and refreshes it automatically. It is never written into a config file.

See Anthropic's own guide: Connect Claude Code to tools via MCP.

 

Codex CLI

Node.js and a Codex-enabled OpenAI account are required. A standard ChatGPT login may not include Codex access, so confirm account access before starting.

  1. Install Codex CLI, if not already installed:
    npm install -g @openai/codex
  2. Add the server:
    codex mcp add timedoctor --url https://api2.timedoctor.com/api/2.0/mcp/mcp
  3. Sign in:
    codex mcp login timedoctor
  4. Complete the sign-in in the browser, then start a Codex session. If Codex does not use the tools automatically, mention Time Doctor directly in the request.

Alternative: edit the config file directly. Add the same server by hand. Open ~/.codex/config.toml on Mac and Linux, or %USERPROFILE%\.codex\config.toml on Windows, and add:

[mcp_servers.timedoctor]
url = "https://api2.timedoctor.com/api/2.0/mcp/mcp"

Then run the sign-in command from step three.

See OpenAI's own guide: MCP in Codex.


Gemini

The Gemini web app does not support custom MCP connections. Use Gemini CLI instead.

  1. Install Gemini CLI, if not already installed:
    npm install -g @google/gemini-cli
  2. Open the settings file at ~/.gemini/settings.json and add Time Doctor.

If the file is empty or new, use the whole block:

{
  "mcpServers": {
    "timedoctor": {
      "httpUrl": "https://api2.timedoctor.com/api/2.0/mcp/mcp"
    }
  }
}

 

If the file already lists other servers, add only the Time Doctor entry inside the existing mcpServers section:

"timedoctor": {
 "httpUrl": "https://api2.timedoctor.com/api/2.0/mcp/mcp"
}

    • Start Gemini CLI and sign in:
      /mcp auth timedoctor
    • Complete the sign-in in the browser. Run /mcp to confirm Time Doctor is connected and to see its tools.

Gemini CLI stores the sign-in at ~/.gemini/mcp-oauth-tokens.json.

See Google's own guide: MCP servers with the Gemini CLI.

 

Warp

Warp is a terminal with a built-in AI agent, so the connection is made from its settings rather than with a command.

  1. Open Settings, then MCP Servers, and click + Add. This can also be reached from Warp Drive, then Personal, then MCP Servers.
  2. Choose the option to add a server by URL, and enter Time Doctor as the name with the Time Doctor server URL.

    Warp lists this option as SSE Server (URL). Use the Time Doctor server URL exactly as shown. If a version of Warp offers a choice between SSE and HTTP or streamable HTTP, choose the HTTP option, since that is what Time Doctor uses.
  3. Start the server. Warp opens a browser window to sign in with Time Doctor and click Allow access.

    Warp lists the Time Doctor tools once connected. Ask about the data directly in the terminal.

Leave any token or environment variable fields empty. Warp starts the browser sign-in only when no credentials are set.

To manage the connection later, return to the same page to start, stop, or delete the server. A stopped server stays stopped the next time Warp opens.

See Warp's own guide: Model Context Protocol.

 

Try the First Question

In any of the tools, paste this:

"Help me get started with my Time Doctor data. Ask me about my goals and build my first report."

 

Advanced: Connect With an API Key

If the tool runs somewhere that cannot open a browser, for example a server or a scheduled job, use an API key instead of signing in. Create one in Time Doctor under Settings / AI connections, then send it as an x-api-key header.

  • Claude Code:
    claude mcp add --transport http --scope user timedoctor https://api2.timedoctor.com/api/2.0/mcp/mcp --header "x-api-key: YOUR_API_KEY"
  • Codex CLI: add an http_headers entry to the server block in config.toml, or use env_http_headers to read the key from an environment variable, which keeps it out of the file.
  • Gemini CLI: add a headers block to the server entry in settings.json.

Treat the key like a password: keep it private, do not share it, and revoke it anytime from Settings / AI connections. For a full walkthrough, see Connect Autonomous AI Agents to Time Doctor.

 

Troubleshooting

Problem

Fix

The command is not recognized

The tool is not installed, or the terminal was open before installation finished. Close the terminal, open a new one, and try again.

The browser sign-in page does not open

Check that the browser did not block the pop-up. If the tool prints a sign-in link, copy it into a browser instead.

Sign-in fails, or a permissions error appears

Confirm with a Time Doctor Owner or Admin that the Time Doctor MCP is enabled in Settings / AI connections, and that the role is Owner, Admin, or Manager.

Claude Code shows "Needs authentication"

Run /mcp and sign in again. If that fails, run claude mcp logout timedoctor, then sign in once more.

Codex asks for sign-in again after restarting

Run codex mcp login timedoctor again. Codex has known issues holding a sign-in across restarts on some versions.

Codex sign-in fails immediately

Confirm the Codex CLI version is current, then try again. If it keeps failing, use the API key method above.

The tool answers without using Time Doctor data

Name it directly, for example: "Using Time Doctor, show hours tracked this week."

A config file change has no effect

Restart the tool. Config files are read at start-up.

Warp asks for a token instead of opening a browser

Clear any token or environment variable set on the server, then start it again. Warp only offers the browser sign-in when no credentials are configured.

Time Doctor is missing after restarting Warp

A stopped server stays stopped. Open Settings, then MCP Servers, and start it.

Warp adds the server but no Time Doctor tools appear

Check the connection type. Time Doctor uses streamable HTTP. If a version of Warp offers both SSE and HTTP, choose HTTP and start the server again. If it only offers SSE Server (URL), use the same URL, then contact support@timedoctor.com if the tools still do not load.

A command or screen does not match the steps above

These tools update frequently. Check the tool's own guide, linked at the end of each section, for its current commands.

 

Disconnecting

  • Claude Code: claude mcp remove timedoctor, or claude mcp logout timedoctor to keep the server but clear the sign-in.
  • Codex CLI and Gemini CLI: remove the Time Doctor entry from the config file and restart the tool.

Access can also be ended from the Time Doctor side in Settings / AI connections, which immediately stops that tool from reading the data.

 

Next Step

See Getting Started — What to Ask Your Time Doctor MCP for examples of what to ask.

 

 

 

 

Should there be any inconsistencies or concerns regarding the article, contact support@timedoctor.com for prompt assistance.