timedoctor-mcp by frifster - MCP Server

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:

Install uv: brew install uv (macOS) or see uv installation
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:

Open VS Code Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
Run MCP: Add Server to configure via UI
Or manually edit .vscode/mcp.json as shown above
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

Login: Playwright automation logs into Time Doctor web interface
Navigate: Goes to Projects & Tasks report
Date Navigation: Uses arrow buttons to change dates
Extract: Parses Angular Material tree structure for project/task data
Parse: Converts "3h 50m" format to decimal hours
Aggregate: Combines duplicate tasks
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:

Verify config path is correct
Check JSON syntax is valid (use a JSON validator)
Ensure Python path is absolute, not relative
Completely quit and restart Claude
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 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"

frifster/timedoctor-mcp

Time Doctor MCP

What It Does

Installation Methods

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

Option B: Clone & Install (For Development)

2. Configure Credentials

3. Add to Claude Desktop/Code

4. Restart Claude

Alternative MCP Clients

Cursor IDE

Google Gemini CLI

VS Code / GitHub Copilot

Usage

MCP Tools

1. export_weekly_csv

2. get_daily_report

3. get_hours_summary

4. export_today_csv

How It Works

Architecture

Project Structure

Troubleshooting

MCP Server Won't Start

Playwright Browser Error

Login Fails

No Data Returned

Claude Not Seeing Tools

Path Issues

Requirements

Performance

Security

Development

Why Web Scraping?

Alternative Installation Methods

Manual pip Installation

Using Python venv (without UV)

Contributing

License

Disclaimer

Support

1. `export_weekly_csv`

2. `get_daily_report`

3. `get_hours_summary`

4. `export_today_csv`