{"id":32784654,"url":"https://github.com/frifster/timedoctor-mcp","last_synced_at":"2026-08-28T04:48:29.673Z","repository":{"id":322449375,"uuid":"1089535092","full_name":"frifster/timedoctor-mcp","owner":"frifster","description":"MCP Server for extracting Time Doctor time tracking data via AI assistants. Fetches time tracking reports from Time Doctor and returns them as CSV data. Integrates with AI assistants via the Model Context Protocol (MCP).","archived":false,"fork":false,"pushed_at":"2025-11-07T00:14:55.000Z","size":201,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-08-27T18:12:41.855Z","etag":null,"topics":["claude","claude-ai","claude-code","copilot","cursor","gemini","mcp-server","timedoctor","timedoctor-export","timedoctor-mcp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frifster.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-04T13:27:28.000Z","updated_at":"2026-07-08T06:33:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/frifster/timedoctor-mcp","commit_stats":null,"previous_names":["frifster/timedoctor-mcp"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/frifster/timedoctor-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frifster%2Ftimedoctor-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frifster%2Ftimedoctor-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frifster%2Ftimedoctor-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frifster%2Ftimedoctor-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frifster","download_url":"https://codeload.github.com/frifster/timedoctor-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frifster%2Ftimedoctor-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36949459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-28T02:00:06.244Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-ai","claude-code","copilot","cursor","gemini","mcp-server","timedoctor","timedoctor-export","timedoctor-mcp"],"created_at":"2025-11-05T02:00:29.468Z","updated_at":"2026-08-28T04:48:29.666Z","avatar_url":"https://github.com/frifster.png","language":"Python","funding_links":["https://buymeacoffee.com/frifster"],"categories":[],"sub_categories":[],"readme":"# Time Doctor MCP\n\n**MCP Server** for extracting Time Doctor time tracking data via AI assistants.\n\n[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support-yellow?style=flat-square\u0026logo=buy-me-a-coffee)](https://buymeacoffee.com/frifster)\n\n## What It Does\n\nFetches time tracking reports from Time Doctor and returns them as CSV data. Integrates with AI assistants via the Model Context Protocol (MCP).\n\n**Supports:**\n- 🤖 Claude Desktop \u0026 Claude Code\n- 🎯 Cursor IDE\n- ✨ Google Gemini CLI\n- 💻 VS Code with GitHub Copilot\n\n**Features:**\n- 🚀 Single-session scraping (login once, get multiple dates)\n- 📅 Works with any date range (1 day to 365+ days)\n- 📊 Returns CSV data as text (no file system issues)\n- ⏱️ Parses Time Doctor's \"3h 50m\" format\n- 📦 Aggregates duplicate tasks\n- ✅ Includes TOTAL row\n\n## Installation Methods\n\n### Option A: Using uvx (Easiest - No Installation Required)\n\nThe simplest way to use Time Doctor MCP is with `uvx`, which automatically downloads the package from PyPI and runs it locally without manual installation:\n\n**Claude Desktop/Code:**\n```json\n{\n  \"mcpServers\": {\n    \"timedoctor\": {\n      \"command\": \"uvx\",\n      \"args\": [\"timedoctor-mcp\"],\n      \"env\": {\n        \"TD_EMAIL\": \"your-email@example.com\",\n        \"TD_PASSWORD\": \"your-password\",\n        \"TD_BASE_URL\": \"https://2.timedoctor.com\",\n        \"HEADLESS\": \"true\"\n      }\n    }\n  }\n}\n```\n\n**Prerequisites:**\n1. Install uv: `brew install uv` (macOS) or see [uv installation](https://docs.astral.sh/uv/)\n2. Install Playwright browsers (one-time setup):\n   ```bash\n   uvx --with playwright playwright install chromium\n   ```\n\n   This downloads the Chromium browser binaries needed for web scraping (~130MB). You only need to run this once.\n\n**That's it!** No cloning, no virtual environments, no setup scripts. Just add the configuration and restart your AI assistant.\n\n### Option B: Clone \u0026 Install (For Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/frifster/timedoctor-mcp.git\ncd timedoctor-mcp\n\n# Install UV (fastest method)\nbrew install uv\n\n# Run setup\n./setup-with-uv.sh\n```\n\n### 2. Configure Credentials\n\nCreate `.env` in the project root:\n```bash\nnano .env\n```\n\nAdd your Time Doctor credentials:\n```env\nTD_EMAIL=your-email@example.com\nTD_PASSWORD=your-password\nTD_BASE_URL=https://2.timedoctor.com\nHEADLESS=true\n```\n\n### 3. Add to Claude Desktop/Code\n\nEdit your Claude MCP configuration:\n\n**macOS:**\n```bash\nopen ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n```\n\n**Windows:**\n```bash\nnotepad %APPDATA%\\Claude\\claude_desktop_config.json\n```\n\n**Linux:**\n```bash\nnano ~/.config/Claude/claude_desktop_config.json\n```\n\nAdd this configuration (replace `\u003cPATH_TO_REPO\u003e` with your actual path):\n\n**Option A: Credentials in JSON**\n```json\n{\n  \"mcpServers\": {\n    \"timedoctor\": {\n      \"command\": \"\u003cPATH_TO_REPO\u003e/.venv/bin/python\",\n      \"args\": [\"\u003cPATH_TO_REPO\u003e/src/mcp_server.py\"],\n      \"env\": {\n        \"TD_EMAIL\": \"your-email@example.com\",\n        \"TD_PASSWORD\": \"your-password\",\n        \"TD_BASE_URL\": \"https://2.timedoctor.com\",\n        \"HEADLESS\": \"true\"\n      }\n    }\n  }\n}\n```\n\n**Option B: Load from .env (Recommended)**\n```json\n{\n  \"mcpServers\": {\n    \"timedoctor\": {\n      \"command\": \"\u003cPATH_TO_REPO\u003e/.venv/bin/python\",\n      \"args\": [\"\u003cPATH_TO_REPO\u003e/src/mcp_server.py\"]\n    }\n  }\n}\n```\n\n**Example paths:**\n- macOS: `/Users/yourname/timedoctor-mcp/.venv/bin/python`\n- Linux: `/home/yourname/timedoctor-mcp/.venv/bin/python`\n- Windows: `C:\\Users\\yourname\\timedoctor-mcp\\.venv\\Scripts\\python.exe`\n\n### 4. Restart Claude\n\nCompletely quit and reopen Claude Desktop/Code.\n\n## Alternative MCP Clients\n\nThis MCP server also works with other AI assistants that support the Model Context Protocol:\n\n### Cursor IDE\n\nEdit your Cursor MCP configuration file:\n\n**macOS/Linux:**\n```bash\nnano ~/.cursor/mcp.json\n```\n\n**Windows:**\n```bash\nnotepad %USERPROFILE%\\.cursor\\mcp.json\n```\n\n**Using uvx (easiest):**\n```json\n{\n  \"mcpServers\": {\n    \"timedoctor\": {\n      \"command\": \"uvx\",\n      \"args\": [\"timedoctor-mcp\"],\n      \"env\": {\n        \"TD_EMAIL\": \"your-email@example.com\",\n        \"TD_PASSWORD\": \"your-password\",\n        \"TD_BASE_URL\": \"https://2.timedoctor.com\",\n        \"HEADLESS\": \"true\"\n      }\n    }\n  }\n}\n```\n\n**Using local installation (for development):**\n```json\n{\n  \"mcpServers\": {\n    \"timedoctor\": {\n      \"command\": \"\u003cPATH_TO_REPO\u003e/.venv/bin/python\",\n      \"args\": [\"\u003cPATH_TO_REPO\u003e/src/mcp_server.py\"],\n      \"env\": {\n        \"TD_EMAIL\": \"your-email@example.com\",\n        \"TD_PASSWORD\": \"your-password\",\n        \"TD_BASE_URL\": \"https://2.timedoctor.com\",\n        \"HEADLESS\": \"true\"\n      }\n    }\n  }\n}\n```\n\n**Note:** You can also create a project-specific configuration at `.cursor/mcp.json` in your project root.\n\n**Restart Cursor** after saving the configuration.\n\n### Google Gemini CLI\n\nEdit your Gemini CLI settings:\n\n**macOS/Linux:**\n```bash\nnano ~/.gemini/settings.json\n```\n\n**Windows:**\n```bash\nnotepad %USERPROFILE%\\.gemini\\settings.json\n```\n\n**Using uvx (easiest):**\n```json\n{\n  \"mcpServers\": {\n    \"timedoctor\": {\n      \"command\": \"uvx\",\n      \"args\": [\"timedoctor-mcp\"],\n      \"env\": {\n        \"TD_EMAIL\": \"your-email@example.com\",\n        \"TD_PASSWORD\": \"your-password\",\n        \"TD_BASE_URL\": \"https://2.timedoctor.com\",\n        \"HEADLESS\": \"true\"\n      },\n      \"timeout\": 600000\n    }\n  }\n}\n```\n\n**Using local installation (for development):**\n```json\n{\n  \"mcpServers\": {\n    \"timedoctor\": {\n      \"command\": \"\u003cPATH_TO_REPO\u003e/.venv/bin/python\",\n      \"args\": [\"\u003cPATH_TO_REPO\u003e/src/mcp_server.py\"],\n      \"env\": {\n        \"TD_EMAIL\": \"your-email@example.com\",\n        \"TD_PASSWORD\": \"your-password\",\n        \"TD_BASE_URL\": \"https://2.timedoctor.com\",\n        \"HEADLESS\": \"true\"\n      },\n      \"timeout\": 600000\n    }\n  }\n}\n```\n\n**Optional settings:**\n- `timeout`: Request timeout in milliseconds (default: 600,000ms)\n- `trust`: Set to `true` to skip tool confirmations\n\n**Restart Gemini CLI** after saving the configuration.\n\n### VS Code / GitHub Copilot\n\nCreate or edit the MCP configuration file:\n\n**Workspace-specific (recommended):**\n```bash\nmkdir -p .vscode\nnano .vscode/mcp.json\n```\n\n**User-wide (all workspaces):**\n- macOS: `~/Library/Application Support/Code/User/mcp.json`\n- Linux: `~/.config/Code/User/mcp.json`\n- Windows: `%APPDATA%\\Code\\User\\mcp.json`\n\n**Using uvx (easiest):**\n```json\n{\n  \"servers\": {\n    \"timedoctor\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"timedoctor-mcp\"],\n      \"env\": {\n        \"TD_EMAIL\": \"your-email@example.com\",\n        \"TD_PASSWORD\": \"your-password\",\n        \"TD_BASE_URL\": \"https://2.timedoctor.com\",\n        \"HEADLESS\": \"true\"\n      }\n    }\n  }\n}\n```\n\n**Using local installation (for development):**\n```json\n{\n  \"servers\": {\n    \"timedoctor\": {\n      \"type\": \"stdio\",\n      \"command\": \"\u003cPATH_TO_REPO\u003e/.venv/bin/python\",\n      \"args\": [\"\u003cPATH_TO_REPO\u003e/src/mcp_server.py\"],\n      \"env\": {\n        \"TD_EMAIL\": \"your-email@example.com\",\n        \"TD_PASSWORD\": \"your-password\",\n        \"TD_BASE_URL\": \"https://2.timedoctor.com\",\n        \"HEADLESS\": \"true\"\n      }\n    }\n  }\n}\n```\n\n**Using .env file with local installation:**\n```json\n{\n  \"servers\": {\n    \"timedoctor\": {\n      \"type\": \"stdio\",\n      \"command\": \"\u003cPATH_TO_REPO\u003e/.venv/bin/python\",\n      \"args\": [\"\u003cPATH_TO_REPO\u003e/src/mcp_server.py\"],\n      \"envFile\": \"\u003cPATH_TO_REPO\u003e/.env\"\n    }\n  }\n}\n```\n\n**Enable in GitHub Copilot:**\n1. Open VS Code Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)\n2. Run **MCP: Add Server** to configure via UI\n3. Or manually edit `.vscode/mcp.json` as shown above\n4. In Copilot Chat, click the tools icon to see available MCP servers\n\n**Restart VS Code** after saving the configuration.\n\n## Usage\n\n**Get data for date range:**\n```\nGet my Time Doctor data from August 25 to September 5\n```\n\n**Today's data:**\n```\nShow me my Time Doctor hours for today\n```\n\n**Last week:**\n```\nGet my Time Doctor data for the last 7 days\n```\n\n**Custom analysis:**\n```\nGet my Time Doctor data from last month and tell me which project took the most time\n```\n\nClaude will receive CSV data like:\n```csv\nDate,Project,Task,Description,WORK HOUR\n08/25/2025,Jira: AYR BMS,ABMS-606,Code Review,5.00\n08/25/2025,Jira: AYR BMS,ABMS-700,Bug Fix,3.50\nTOTAL,,,,8.50\n```\n\nYou can then ask Claude to save it wherever you want!\n\n## MCP Tools\n\n### 1. `export_weekly_csv`\nGet time tracking data for any date range in CSV format.\n\n**Parameters:**\n- `start_date` (required): YYYY-MM-DD format\n- `end_date` (required): YYYY-MM-DD format\n\n**Returns:** CSV data as text with summary statistics\n\n### 2. `get_daily_report`\nGet detailed report for a specific date.\n\n**Parameters:**\n- `date` (required): YYYY-MM-DD format or \"today\"\n\n**Returns:** Formatted report with project breakdown\n\n### 3. `get_hours_summary`\nQuick hours breakdown by project.\n\n**Parameters:**\n- `date` (required): YYYY-MM-DD format or \"today\"\n\n**Returns:** Summary by project\n\n### 4. `export_today_csv`\nQuick access to today's data.\n\n**Parameters:** None\n\n**Returns:** Today's CSV data with summary\n\n## How It Works\n\n1. **Login:** Playwright automation logs into Time Doctor web interface\n2. **Navigate:** Goes to Projects \u0026 Tasks report\n3. **Date Navigation:** Uses arrow buttons to change dates\n4. **Extract:** Parses Angular Material tree structure for project/task data\n5. **Parse:** Converts \"3h 50m\" format to decimal hours\n6. **Aggregate:** Combines duplicate tasks\n7. **Return:** CSV data as text in MCP response\n\n## Architecture\n\n**Single-Session Efficiency:**\n- Login once\n- Navigate through all dates in one session\n- Extract data for each date\n- Close browser once\n- **Result:** 2-3x faster than logging in for each date\n\n**CSV Data Format:**\n```csv\nDate,Project,Task,Description,WORK HOUR\n11/04/2025,Jira: AYR BMS,ABMS-606,Code Review - ABMS-606,0.25\n11/04/2025,Jira: AYR BMS,ABMS-4979,Deal template update,2.47\nTOTAL,,,,2.72\n```\n\n- **Date:** MM/DD/YYYY format\n- **WORK HOUR:** Decimal hours (5.00, 1.50, 0.25)\n- **TOTAL:** Sum of all hours\n\n## Project Structure\n\n```\ntimedoctor-mcp/\n├── .env                    # Your credentials (git-ignored)\n├── .env.example            # Example configuration\n├── requirements.txt        # Python dependencies\n├── setup-with-uv.sh       # Setup script\n├── src/\n│   ├── scraper.py         # Browser automation \u0026 login\n│   ├── parser.py          # HTML parsing (Angular Material tree)\n│   ├── transformer.py     # CSV formatting\n│   └── mcp_server.py      # MCP server with 4 tools\n└── tests/\n    ├── debug_login.py     # Login debugging tool\n    ├── test_parser.py     # HTML parsing tests\n    ├── test_date_navigation.py  # Date navigation tests\n    └── test_complete_flow.py    # End-to-end tests\n```\n\n## Troubleshooting\n\n### MCP Server Won't Start\n\nCheck the log:\n```bash\ntail -f timedoctor_mcp.log\n```\n\nCommon issues:\n- ❌ **Missing credentials:** Add to `.env` or MCP config\n- ❌ **Wrong Python path:** Use `.venv/bin/python` (or `.venv/Scripts/python.exe` on Windows)\n- ❌ **Dependencies not installed:** Run `./setup-with-uv.sh`\n- ❌ **Playwright browsers not installed:** Run `uvx --with playwright playwright install chromium`\n\n### Playwright Browser Error\n\nIf you see:\n```\nError: BrowserType.launch: Executable doesn't exist at .../chromium_headless_shell-1187/chrome-mac/headless_shell\n```\n\n**Solution:**\n```bash\nuvx --with playwright playwright install chromium\n```\n\nThis is a one-time setup that downloads the browser binaries (~130MB). You only need to run this once per system.\n\n### Login Fails\n\n**Check log for:**\n```\nLogin failed - still on login page\n```\n\n**Solutions:**\n- Verify credentials in `.env` are correct\n- Check if Time Doctor requires 2FA (not supported)\n- Try logging in manually at https://2.timedoctor.com/login\n- Look for error messages in the log\n\n**The scraper logs which email it's using:**\n```\nTimeDoctorScraper initialized with email: your-email@example.com\n```\n\n### No Data Returned\n\n**Check log for:**\n```\nParsed 0 time entries\n```\n\n**Solutions:**\n- Verify you have time tracking data for those dates\n- Check that \"Expand All\" button appears on the report page\n- Try with today's date first to confirm it works\n- Check log for HTML parsing errors\n\n### Claude Not Seeing Tools\n\n**Solutions:**\n1. Verify config path is correct\n2. Check JSON syntax is valid (use a JSON validator)\n3. Ensure Python path is absolute, not relative\n4. Completely quit and restart Claude\n5. Check Claude settings → MCP Servers\n\n### Path Issues\n\nMake sure all paths in your MCP config are **absolute paths**, not relative:\n\n✅ **Good:**\n- macOS/Linux: `/Users/name/timedoctor-mcp/.venv/bin/python`\n- Windows: `C:\\Users\\name\\timedoctor-mcp\\.venv\\Scripts\\python.exe`\n\n❌ **Bad:**\n- `~/timedoctor-mcp/.venv/bin/python` (tilde not expanded)\n- `./timedoctor-mcp/.venv/bin/python` (relative path)\n- `timedoctor-mcp/.venv/bin/python` (relative path)\n\n## Requirements\n\n- **Python:** 3.12 or 3.13 (3.14 not supported yet)\n- **Dependencies:** Playwright, BeautifulSoup4, MCP SDK, python-dotenv\n- **System:** macOS, Linux, Windows\n- **Time Doctor:** Active account with login credentials\n\n## Performance\n\n**Single-session architecture:**\n- **7 days:** ~45 seconds (vs ~90 seconds with multiple logins)\n- **30 days:** ~3 minutes\n- **Login:** 5 seconds (once)\n- **Per date:** 3-4 seconds (navigation + extraction)\n\n## Security\n\n- ✅ Credentials stored in `.env` (git-ignored)\n- ✅ Headless browser (no GUI)\n- ✅ Local execution only\n- ✅ No data sent to third parties\n- ⚠️ Store `.env` securely (`chmod 600 .env` recommended)\n\n## Development\n\n**Test login:**\n```bash\nsource .venv/bin/activate  # or .venv\\Scripts\\activate on Windows\npython tests/debug_login.py\n```\n\n**Test parsing:**\n```bash\npython tests/test_parser.py\n```\n\n**Test complete flow:**\n```bash\npython tests/test_complete_flow.py\n```\n\n**View logs:**\n```bash\ntail -f timedoctor_mcp.log\n```\n\n## Why Web Scraping?\n\nTime Doctor has an API, but this MCP server uses web automation because:\n- ✅ No API token setup needed\n- ✅ Same access as web interface\n- ✅ Works with all Time Doctor plans\n- ✅ More reliable for \"Projects \u0026 Tasks\" report\n\nIf you prefer API access, Time Doctor's API is available at: `https://api2.timedoctor.com/api/1.0/`\n\n## Alternative Installation Methods\n\n### Manual pip Installation\n\n```bash\n# Create virtual environment\npython3.13 -m venv .venv\nsource .venv/bin/activate  # or .venv\\Scripts\\activate on Windows\n\n# Install dependencies\npip install -r requirements.txt\n\n# Install Playwright browsers\nplaywright install chromium\n```\n\n### Using Python venv (without UV)\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nplaywright install chromium\n```\n\n## Contributing\n\nContributions welcome! Please feel free to submit issues or pull requests.\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\nThis 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.\n\n## Support\n\nIf this tool saves you time, consider buying me a coffee! ☕\n\n[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support-yellow?style=for-the-badge\u0026logo=buy-me-a-coffee)](https://buymeacoffee.com/frifster)\n\n---\n\n**Questions?** Check the log file: `timedoctor_mcp.log` in the project directory\n\n**Working?** Ask Claude: \"Get my Time Doctor data for today\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrifster%2Ftimedoctor-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrifster%2Ftimedoctor-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrifster%2Ftimedoctor-mcp/lists"}