使用说明

时间医生MCP

MCP服务器 用于通过AI助手提取Time Doctor时间跟踪数据。

它做什么

从time Doctor获取时间跟踪报告，并将其作为CSV数据返回。通过模型上下文协议（MCP）与AI助手集成。

支持：

🤖 克劳德桌面和克劳德代码
🎯 光标IDE
✨ 谷歌Gemini CLI
💻 VS代码与GitHub Copilot

特征：

🚀 单会话抓取（登录一次，获取多个日期）
📅 适用于任何日期范围（1天至365+天）
📊 以文本形式返回CSV数据（无文件系统问题）
⏱️ 解析Time Doctor的“3小时50米”格式
📦 聚合重复任务
✅ 包括总计行

安装方法

选项A：使用uvx（最简单-无需安装）

使用Time Doctor MCP的最简单方法是 uvx，它会自动从PyPI下载包并在本地运行，而无需手动安装：

克劳德桌面/代码：

{
  "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"
      }
    }
  }
}

先决条件：

安装紫外线： brew install uv （macOS）或查看紫外线装置
安装Playwright浏览器（一次性设置）：
```
uvx --with playwright playwright install chromium
```
这将下载网络抓取所需的Chromium浏览器二进制文件（约130MB）。你只需要运行一次。

就是这样！ 没有克隆，没有虚拟环境，没有安装脚本。只需添加配置并重新启动您的AI助手。

选项B：克隆和安装（用于开发）

# 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.配置凭据

创建 .env 在项目根目录中：

nano .env

添加您的时间医生凭据：

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

3.添加到克劳德桌面/代码

编辑您的Claude MCP配置：

macOS：

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

窗户：

notepad %APPDATA%\Claude\claude_desktop_config.json

Linux：

nano ~/.config/Claude/claude_desktop_config.json

添加此配置（替换 <PATH_TO_REPO> 根据您的实际路径）：

选项A：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"
      }
    }
  }
}

选项B：从.env加载（推荐）

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

示例路径：

macOS： /Users/yourname/timedoctor-mcp/.venv/bin/python
Linux： /home/yourname/timedoctor-mcp/.venv/bin/python
窗户： C:\Users\yourname\timedoctor-mcp\.venv\Scripts\python.exe

4.重启克劳德

完全退出并重新打开克劳德桌面/代码。

替代MCP客户端

此MCP服务器还可与支持模型上下文协议的其他AI助手配合使用：

光标IDE

编辑光标MCP配置文件：

macOS/Linux：

nano ~/.cursor/mcp.json

窗户：

notepad %USERPROFILE%\.cursor\mcp.json

使用uvx（最简单）：

{
  "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"
      }
    }
  }
}

使用本地安装（用于开发）：

{
  "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"
      }
    }
  }
}

注：您还可以在以下位置创建特定于项目的配置 .cursor/mcp.json 在您的项目根目录中。

重新启动游标 保存配置后。

谷歌Gemini CLI

编辑Gemini CLI设置：

macOS/Linux：

nano ~/.gemini/settings.json

窗户：

notepad %USERPROFILE%\.gemini\settings.json

使用uvx（最简单）：

{
  "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
    }
  }
}

使用本地安装（用于开发）：

{
  "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
    }
  }
}

可选设置：

timeout：请求超时（毫秒）（默认值：600000ms）
trust：设置为 true 跳过工具确认

重新启动Gemini CLI 保存配置后。

VS代码/GitHub副本

创建或编辑MCP配置文件：

特定于工作区（推荐）：

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

用户范围（所有工作区）：

macOS： ~/Library/Application Support/Code/User/mcp.json
Linux： ~/.config/Code/User/mcp.json
窗户： %APPDATA%\Code\User\mcp.json

使用uvx（最简单）：

{
  "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"
      }
    }
  }
}

使用本地安装（用于开发）：

{
  "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"
      }
    }
  }
}

在本地安装时使用.env文件：

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

在GitHub Copilot中启用：

打开VS代码命令面板(Cmd+Shift+P 或 Ctrl+Shift+P)
跑 MCP：添加服务器 通过用户界面进行配置
或手动编辑 .vscode/mcp.json 如上文所示
在Copilot聊天中，单击工具图标查看可用的MCP服务器

重新启动VS代码 保存配置后。

用法

获取日期范围的数据：

Get my Time Doctor data from August 25 to September 5

今日数据：

Show me my Time Doctor hours for today

上周：

Get my Time Doctor data for the last 7 days

自定义分析：

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

Claude将收到CSV数据，如：

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

然后，你可以让克劳德把它保存在任何你想保存的地方！

MCP工具

1. `export_weekly_csv`

获取CSV格式的任何日期范围的时间跟踪数据。

参数：

start_date （必填）：YYYY-MM-DD格式
end_date （必填）：YYYY-MM-DD格式

退货： CSV数据以文本形式显示，并附有统计摘要

2. `get_daily_report`

获取特定日期的详细报告。

参数：

date （必填）：YYYY-MM-DD格式或“今天”

退货： 包含项目细分的格式化报告

3. `get_hours_summary`

按项目快速细分小时数。

参数：

date （必填）：YYYY-MM-DD格式或“今天”

退货： 按项目汇总

4. `export_today_csv`

快速访问今天的数据。

参数： 无

退货： 今天的CSV数据及其摘要

运作原理

登录： 剧作家自动化登录到Time Doctor web界面
导航： 转到项目和任务报告
日期导航： 使用箭头按钮更改日期
提取物： 解析项目/任务数据的角度材质树结构
解析： 将“3h-50m”格式转换为十进制小时
总计： 合并重复任务
返回： CSV数据作为MCP响应中的文本

建筑

单会话效率：

登录一次
在一个会话中浏览所有日期
提取每个日期的数据
关闭浏览器一次
结果： 每个日期比登录快2-3倍

CSV数据格式：

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

日期： MM/DD/YYYY格式
工作时间： 十进制小时（5.00、1.50、0.25）
总计： 所有小时的总和

项目结构

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

故障排除

MCP服务器无法启动

检查日志：

tail -f timedoctor_mcp.log

常见问题：

❌ 缺少凭据： 添加到 .env 或MCP配置
❌ 错误的Python路径： 使用 .venv/bin/python （或 .venv/Scripts/python.exe 在Windows上）
❌ 未安装依赖项： 跑 ./setup-with-uv.sh
❌ 未安装Playwright浏览器： 跑 uvx --with playwright playwright install chromium

剧作家浏览器错误

如果你看到：

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

解决方案：

uvx --with playwright playwright install chromium

这是一个一次性设置，用于下载浏览器二进制文件（约130MB）。每个系统只需要运行一次。

登录失败

检查日志：

Login failed - still on login page

解决：

验证中的凭据 .env 是正确的
检查Time Doctor是否需要2FA（不支持）
尝试手动登录https://2.timedoctor.com/login
在日志中查找错误消息

scraper会记录它正在使用的电子邮件：

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

未返回数据

检查日志：

Parsed 0 time entries

解决：

验证您是否有这些日期的时间跟踪数据
检查报告页面上是否出现“全部展开”按钮
先试试今天的日期，确认它是否有效
检查日志中的HTML分析错误

克劳德看不到工具

解决：

验证配置路径是否正确
检查JSON语法是否有效（使用JSON验证器）
确保Python路径是绝对的，而不是相对的
完全退出并重新启动Claude
检查Claude设置→ MCP服务器

路径问题

确保MCP配置中的所有路径 绝对路径，不是相对的：

✅ 好：

macOS/Linux： /Users/name/timedoctor-mcp/.venv/bin/python
窗户： C:\Users\name\timedoctor-mcp\.venv\Scripts\python.exe

❌ 坏：

~/timedoctor-mcp/.venv/bin/python （波浪号未展开）
./timedoctor-mcp/.venv/bin/python （相对路径）
timedoctor-mcp/.venv/bin/python （相对路径）

需求

python 3.12或3.13（3.14尚不支持）
依赖关系： 剧作家、BeautifulSoup4、MCP SDK、python dotenv
系统： macOS、Linux、Windows
时间医生： 具有登录凭据的活动帐户

演出

单会话架构：

7天： 约45秒（多次登录约90秒）
30天： 约3分钟
登录： 5秒（一次）
按日期： 3-4秒（导航+提取）

安全

✅ 凭据存储在 .env （忽略git）
✅ 无头浏览器（无GUI）
✅ 仅限本地执行
✅ 未向第三方发送数据
⚠️ 商店 .env 安全(chmod 600 .env 推荐）

发展

测试登录：

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

测试解析：

python tests/test_parser.py

测试完整流程：

python tests/test_complete_flow.py

查看日志：

tail -f timedoctor_mcp.log

为什么要抓取网页？

Time Doctor有API，但此MCP服务器使用网络自动化，因为：

✅ 不需要设置API令牌
✅ 与web界面相同的访问权限
✅ 适用于所有Time Doctor计划
✅ “项目和任务”报告更可靠

如果您更喜欢API访问，Time Doctor的API可访问： https://api2.timedoctor.com/api/1.0/

其他安装方法

手动管道安装

# 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

使用Python venv（无UV）

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

贡献

欢迎投稿！请随时提交问题或拉取请求。

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

免责声明

此工具用于个人使用和自动化您自己的Time Doctor数据。使用此刮刀时，请确保您遵守Time Doctor的服务条款和您所在组织的政策。

支持

如果这个工具能节省你的时间，可以考虑给我买杯咖啡！ ☕

问题？ 检查日志文件： timedoctor_mcp.log 在项目目录中

工作？ 问克劳德：“获取我今天的时间医生数据”

使用说明

时间医生MCP

它做什么

安装方法

选项A：使用uvx（最简单-无需安装）

选项B：克隆和安装（用于开发）

2.配置凭据

3.添加到克劳德桌面/代码

4.重启克劳德

替代MCP客户端

光标IDE

谷歌Gemini CLI

VS代码/GitHub副本

用法

MCP工具

1. export_weekly_csv

2. get_daily_report

3. get_hours_summary

4. export_today_csv

运作原理

建筑

项目结构

故障排除

MCP服务器无法启动

剧作家浏览器错误

登录失败

未返回数据

克劳德看不到工具

路径问题

需求

演出

安全

发展

为什么要抓取网页？

其他安装方法

手动管道安装

使用Python venv（无UV）

贡献

许可证

免责声明

支持

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

网页数据提取 MCP 服务

1. `export_weekly_csv`

2. `get_daily_report`

3. `get_hours_summary`

4. `export_today_csv`