Time Doctor MCP

MCP Server for extracting Time Doctor time tracking data via AI assistants.

What It Does

Fetches time tracking reports from Time Doctor and returns them as CSV data. Integrates with AI assistants via the Model Context Protocol (MCP).

Supports:

• 🤖 Claude Desktop & Claude Code

• 🎯 Cursor IDE

• ✨ Google Gemini CLI

• 💻 VS Code with GitHub Copilot

Features:

• 🚀 Single-session scraping (login once, get multiple dates)

• 📅 Works with any date range (1 day to 365+ days)

• 📊 Returns CSV data as text (no file system issues)

• ⏱️ Parses Time Doctor's "3h 50m" format

• 📦 Aggregates duplicate tasks

• ✅ Includes TOTAL row

Installation Methods

Option A: Using uvx (Easiest - No Installation Required)

The simplest way to use Time Doctor MCP is with uvx, which automatically downloads the package from PyPI and runs it locally without manual installation:

Claude Desktop/Code:

{
  "mcpServers": {
    "timedoctor": {
      "command": "uvx",
      "args": ["timedoctor-mcp"],
      "env": {
        "TD_EMAIL": "your-email@example.com",
        "TD_PASSWORD": "your-password",
        "TD_BASE_URL": "https://2.timedoctor.com",
        "HEADLESS": "true"
      }
    }
  }
}

Prerequisites:

1. Install uv: brew install uv (macOS) or see uv installation

2. Install Playwright browsers (one-time setup):

   uvx --with playwright playwright install chromium

   This downloads the Chromium browser binaries needed for web scraping (~130MB). You only need to run this once.

That's it! No cloning, no virtual environments, no setup scripts. Just add the configuration and restart your AI assistant.

Option B: Clone & Install (For Development)

# Clone the repository
git clone https://github.com/frifster/timedoctor-mcp.git
cd timedoctor-mcp

# Install UV (fastest method)
brew install uv

# Run setup
./setup-with-uv.sh

2. Configure Credentials

Create .env in the project root:

nano .env

Add your Time Doctor credentials:

TD_EMAIL=your-email@example.com
TD_PASSWORD=your-password
TD_BASE_URL=https://2.timedoctor.com
HEADLESS=true

3. Add to Claude Desktop/Code

Edit your Claude MCP configuration:

macOS:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

Linux:

nano ~/.config/Claude/claude_desktop_config.json

Add this configuration (replace <PATH_TO_REPO> with your actual path):

Option A: Credentials in JSON

{
  "mcpServers": {
    "timedoctor": {
      "command": "<PATH_TO_REPO>/.venv/bin/python",
      "args": ["<PATH_TO_REPO>/src/mcp_server.py"],
      "env": {
        "TD_EMAIL": "your-email@example.com",
        "TD_PASSWORD": "your-password",
        "TD_BASE_URL": "https://2.timedoctor.com",
        "HEADLESS": "true"
      }
    }
  }
}

Option B: Load from .env (Recommended)

{
  "mcpServers": {
    "timedoctor": {
      "command": "<PATH_TO_REPO>/.venv/bin/python",
      "args": ["<PATH_TO_REPO>/src/mcp_server.py"]
    }
  }
}

Example paths:

• macOS: /Users/yourname/timedoctor-mcp/.venv/bin/python

• Linux: /home/yourname/timedoctor-mcp/.venv/bin/python

• Windows: C:\Users\yourname\timedoctor-mcp\.venv\Scripts\python.exe

4. Restart Claude

Completely quit and reopen Claude Desktop/Code.

Alternative MCP Clients

This MCP server also works with other AI assistants that support the Model Context Protocol:

Cursor IDE

Edit your Cursor MCP configuration file:

macOS/Linux:

nano ~/.cursor/mcp.json

Windows:

notepad %USERPROFILE%\.cursor\mcp.json

Using uvx (easiest):

{
  "mcpServers": {
    "timedoctor": {
      "command": "uvx",
      "args": ["timedoctor-mcp"],
      "env": {
        "TD_EMAIL": "your-email@example.com",
        "TD_PASSWORD": "your-password",
        "TD_BASE_URL": "https://2.timedoctor.com",
        "HEADLESS": "true"
      }
    }
  }
}

Using local installation (for development):

{
  "mcpServers": {
    "timedoctor": {
      "command": "<PATH_TO_REPO>/.venv/bin/python",
      "args": ["<PATH_TO_REPO>/src/mcp_server.py"],
      "env": {
        "TD_EMAIL": "your-email@example.com",
        "TD_PASSWORD": "your-password",
        "TD_BASE_URL": "https://2.timedoctor.com",
        "HEADLESS": "true"
      }
    }
  }
}

Note: You can also create a project-specific configuration at .cursor/mcp.json in your project root.

Restart Cursor after saving the configuration.

Google Gemini CLI

Edit your Gemini CLI settings:

macOS/Linux:

nano ~/.gemini/settings.json

Windows:

notepad %USERPROFILE%\.gemini\settings.json

Using uvx (easiest):

{
  "mcpServers": {
    "timedoctor": {
      "command": "uvx",
      "args": ["timedoctor-mcp"],
      "env": {
        "TD_EMAIL": "your-email@example.com",
        "TD_PASSWORD": "your-password",
        "TD_BASE_URL": "https://2.timedoctor.com",
        "HEADLESS": "true"
      },
      "timeout": 600000
    }
  }
}

Using local installation (for development):

{
  "mcpServers": {
    "timedoctor": {
      "command": "<PATH_TO_REPO>/.venv/bin/python",
      "args": ["<PATH_TO_REPO>/src/mcp_server.py"],
      "env": {
        "TD_EMAIL": "your-email@example.com",
        "TD_PASSWORD": "your-password",
        "TD_BASE_URL": "https://2.timedoctor.com",
        "HEADLESS": "true"
      },
      "timeout": 600000
    }
  }
}

Optional settings:

• timeout: Request timeout in milliseconds (default: 600,000ms)

• trust: Set to true to skip tool confirmations

Restart Gemini CLI after saving the configuration.

VS Code / GitHub Copilot

Create or edit the MCP configuration file:

Workspace-specific (recommended):

mkdir -p .vscode
nano .vscode/mcp.json

User-wide (all workspaces):

• macOS: ~/Library/Application Support/Code/User/mcp.json

• Linux: ~/.config/Code/User/mcp.json

• Windows: %APPDATA%\Code\User\mcp.json

Using uvx (easiest):

{
  "servers": {
    "timedoctor": {
      "type": "stdio",
      "command": "uvx",
      "args": ["timedoctor-mcp"],
      "env": {
        "TD_EMAIL": "your-email@example.com",
        "TD_PASSWORD": "your-password",
        "TD_BASE_URL": "https://2.timedoctor.com",
        "HEADLESS": "true"
      }
    }
  }
}

Using local installation (for development):

{
  "servers": {
    "timedoctor": {
      "type": "stdio",
      "command": "<PATH_TO_REPO>/.venv/bin/python",
      "args": ["<PATH_TO_REPO>/src/mcp_server.py"],
      "env": {
        "TD_EMAIL": "your-email@example.com",
        "TD_PASSWORD": "your-password",
        "TD_BASE_URL": "https://2.timedoctor.com",
        "HEADLESS": "true"
      }
    }
  }
}

Using .env file with local installation:

{
  "servers": {
    "timedoctor": {
      "type": "stdio",
      "command": "<PATH_TO_REPO>/.venv/bin/python",
      "args": ["<PATH_TO_REPO>/src/mcp_server.py"],
      "envFile": "<PATH_TO_REPO>/.env"
    }
  }
}

Enable in GitHub Copilot:

1. Open VS Code Command Palette (Cmd+Shift+P or Ctrl+Shift+P)

2. Run MCP: Add Server to configure via UI

3. Or manually edit .vscode/mcp.json as shown above

4. In Copilot Chat, click the tools icon to see available MCP servers

Restart VS Code after saving the configuration.

Usage

Get data for date range:

Get my Time Doctor data from August 25 to September 5

Today's data:

Show me my Time Doctor hours for today

Last week:

Get my Time Doctor data for the last 7 days

Custom analysis:

Get my Time Doctor data from last month and tell me which project took the most time

Claude will receive CSV data like:

Date,Project,Task,Description,WORK HOUR
08/25/2025,Jira: AYR BMS,ABMS-606,Code Review,5.00
08/25/2025,Jira: AYR BMS,ABMS-700,Bug Fix,3.50
TOTAL,,,,8.50

You can then ask Claude to save it wherever you want!

MCP Tools

1. export_weekly_csv

Get time tracking data for any date range in CSV format.

Parameters:

• start_date (required): YYYY-MM-DD format

• end_date (required): YYYY-MM-DD format

Returns: CSV data as text with summary statistics

2. get_daily_report

Get detailed report for a specific date.

Parameters:

• date (required): YYYY-MM-DD format or "today"

Returns: Formatted report with project breakdown

3. get_hours_summary

Quick hours breakdown by project.

Parameters:

• date (required): YYYY-MM-DD format or "today"

Returns: Summary by project

4. export_today_csv

Quick access to today's data.

Parameters: None

Returns: Today's CSV data with summary

How It Works

1. Login: Playwright automation logs into Time Doctor web interface

2. Navigate: Goes to Projects & Tasks report

3. Date Navigation: Uses arrow buttons to change dates

4. Extract: Parses Angular Material tree structure for project/task data

5. Parse: Converts "3h 50m" format to decimal hours

6. Aggregate: Combines duplicate tasks

7. Return: CSV data as text in MCP response

Architecture

Single-Session Efficiency:

• Login once

• Navigate through all dates in one session

• Extract data for each date

• Close browser once

• Result: 2-3x faster than logging in for each date

CSV Data Format:

Date,Project,Task,Description,WORK HOUR
11/04/2025,Jira: AYR BMS,ABMS-606,Code Review - ABMS-606,0.25
11/04/2025,Jira: AYR BMS,ABMS-4979,Deal template update,2.47
TOTAL,,,,2.72

• Date: MM/DD/YYYY format

• WORK HOUR: Decimal hours (5.00, 1.50, 0.25)

• TOTAL: Sum of all hours

Project Structure

timedoctor-mcp/
├── .env                    # Your credentials (git-ignored)
├── .env.example            # Example configuration
├── requirements.txt        # Python dependencies
├── setup-with-uv.sh       # Setup script
├── src/
│   ├── scraper.py         # Browser automation & login
│   ├── parser.py          # HTML parsing (Angular Material tree)
│   ├── transformer.py     # CSV formatting
│   └── mcp_server.py      # MCP server with 4 tools
└── tests/
    ├── debug_login.py     # Login debugging tool
    ├── test_parser.py     # HTML parsing tests
    ├── test_date_navigation.py  # Date navigation tests
    └── test_complete_flow.py    # End-to-end tests

Troubleshooting

MCP Server Won't Start

Check the log:

tail -f timedoctor_mcp.log

Common issues:

• ❌ Missing credentials: Add to .env or MCP config

• ❌ Wrong Python path: Use .venv/bin/python (or .venv/Scripts/python.exe on Windows)

• ❌ Dependencies not installed: Run ./setup-with-uv.sh

• ❌ Playwright browsers not installed: Run uvx --with playwright playwright install chromium

Playwright Browser Error

If you see:

Error: BrowserType.launch: Executable doesn't exist at .../chromium_headless_shell-1187/chrome-mac/headless_shell

Solution:

uvx --with playwright playwright install chromium

This is a one-time setup that downloads the browser binaries (~130MB). You only need to run this once per system.

Login Fails

Check log for:

Login failed - still on login page

Solutions:

• Verify credentials in .env are correct

• Check if Time Doctor requires 2FA (not supported)

• Try logging in manually at https://2.timedoctor.com/login

• Look for error messages in the log

The scraper logs which email it's using:

TimeDoctorScraper initialized with email: your-email@example.com

No Data Returned

Check log for:

Parsed 0 time entries

Solutions:

• Verify you have time tracking data for those dates

• Check that "Expand All" button appears on the report page

• Try with today's date first to confirm it works

• Check log for HTML parsing errors

Claude Not Seeing Tools

Solutions:

1. Verify config path is correct

2. Check JSON syntax is valid (use a JSON validator)

3. Ensure Python path is absolute, not relative

4. Completely quit and restart Claude

5. Check Claude settings → MCP Servers

Path Issues

Make sure all paths in your MCP config are absolute paths, not relative:

✅ Good:

• macOS/Linux: /Users/name/timedoctor-mcp/.venv/bin/python

• Windows: C:\Users\name\timedoctor-mcp\.venv\Scripts\python.exe

❌ Bad:

• ~/timedoctor-mcp/.venv/bin/python (tilde not expanded)

• ./timedoctor-mcp/.venv/bin/python (relative path)

• timedoctor-mcp/.venv/bin/python (relative path)

Requirements

• Python: 3.12 or 3.13 (3.14 not supported yet)

• Dependencies: Playwright, BeautifulSoup4, MCP SDK, python-dotenv

• System: macOS, Linux, Windows

• Time Doctor: Active account with login credentials

Performance

Single-session architecture:

• 7 days: ~45 seconds (vs ~90 seconds with multiple logins)

• 30 days: ~3 minutes

• Login: 5 seconds (once)

• Per date: 3-4 seconds (navigation + extraction)

Security

• ✅ Credentials stored in .env (git-ignored)

• ✅ Headless browser (no GUI)

• ✅ Local execution only

• ✅ No data sent to third parties

• ⚠️ Store .env securely (chmod 600 .env recommended)

Development

Test login:

source .venv/bin/activate  # or .venv\Scripts\activate on Windows
python tests/debug_login.py

Test parsing:

python tests/test_parser.py

Test complete flow:

python tests/test_complete_flow.py

View logs:

tail -f timedoctor_mcp.log

Why Web Scraping?

Time Doctor has an API, but this MCP server uses web automation because:

• ✅ No API token setup needed

• ✅ Same access as web interface

• ✅ Works with all Time Doctor plans

• ✅ More reliable for "Projects & Tasks" report

If you prefer API access, Time Doctor's API is available at: https://api2.timedoctor.com/api/1.0/

Alternative Installation Methods

Manual pip Installation

# Create virtual environment
python3.13 -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium

Using Python venv (without UV)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
playwright install chromium

Contributing

Contributions welcome! Please feel free to submit issues or pull requests.

License

MIT License - See LICENSE file for details.

Disclaimer

This tool is for personal use and automation of your own Time Doctor data. Ensure you comply with Time Doctor's Terms of Service and your organization's policies when using this scraper.

Support

If this tool saves you time, consider buying me a coffee! ☕

Questions? Check the log file: timedoctor_mcp.log in the project directory

Working? Ask Claude: "Get my Time Doctor data for today"