Timesheet

Timesheet MCP 服务

通过 ChatGPT、Claude、Claude Code、Cursor 和 VS Code 等 AI 助手，使用自然语言控制 Timesheet。通过聊天即可启动和停止计时器、记录过去的工作、获取统计数据和导出文件、申请休假，以及管理项目和团队。

该服务支持当前版本的 Model Context Protocol（2026-07-28）和更早版本，因此新旧客户端均可使用。完整指南请访问 docs.timesheet.io。

两种连接方式

	托管服务	本地服务
地址	https://mcp.timesheet.io	在你的计算机上运行 npx -y @timesheet/mcp
登录	Timesheet 账户（OAuth 2.1）或 API 密钥	API 密钥
要求	无	Node.js 20 或更高版本

两种方式提供相同的工具。你需要 Timesheet Pro 或更高级别的套餐，其中包含 API 访问权限。

获取 API 密钥

在 Timesheet Web 应用中，前往 Integrations > API Keys，选择 New API Key，然后复制密钥。相同的密钥可用于托管服务、本地服务和 Timesheet API。

使用托管服务

ChatGPT： 开启开发者模式，使用 URL https://mcp.timesheet.io 添加连接，并在提示时使用你的 Timesheet 账户登录。

Claude Code 使用 API 密钥：

claude mcp add --transport http --scope user timesheet https://mcp.timesheet.io --header "Authorization: Bearer your-api-token-here"

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "timesheet": {
      "url": "https://mcp.timesheet.io",
      "headers": { "Authorization": "Bearer your-api-token-here" }
    }
  }
}

使用本地服务

Claude Code：

claude mcp add timesheet --scope user -e TIMESHEET_API_TOKEN=your-api-token-here -- npx -y @timesheet/mcp

Claude Desktop（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上的 %APPDATA%\Claude\claude_desktop_config.json），以及其他使用相同格式的客户端：

{
  "mcpServers": {
    "timesheet": {
      "command": "npx",
      "args": ["-y", "@timesheet/mcp"],
      "env": {
        "TIMESHEET_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

更改配置后，请重启客户端。指南介绍了 VS Code 和其他客户端的设置方法。

示例提示词

• “启动网站项目的计时器”
• “暂停我的计时器，我去吃午饭”，然后说“停止计时器”
• “记录周一在 API 项目上工作的 2 小时”
• “我昨天做了什么工作？”
• “我在 9 月记录了多少可计费工时？”
• “将 Acme 的 9 月工时表以 PDF 格式发送到 [email protected]”
• “帮我申请下周五休假”
• “我的团队现在有谁在记录工时？”

工具

该服务提供 100 多种工具。助手会自行选择合适的工具，因此你无需指定工具名称。

类别	工具功能
计时器	启动、暂停、恢复、停止和编辑正在运行的计时器
工时记录	列出、创建、更新和删除记录，并添加备注、费用和休息时间
统计数据	获取总计、可计费工时，以及最长一年的项目和每日明细
报告和导出	导出 Excel、CSV 和 PDF，使用导出模板，并导出文档、任务、费用和备注的 PDF
项目、待办事项和标签	管理项目及其成员、待办事项、标签和费率
休假和合同	申请、批准和取消休假，并管理休假类型和合同
团队和组织	管理成员和邀请，并查看当前正在记录工时的人员
账户	查看和更新个人资料及设置

指南列出了所有工具。

交互式卡片

在支持 MCP Apps 的客户端（例如 ChatGPT 和 Claude）中，计时器、新建和已更改的工时记录、统计数据、导出文件和休假申请会以交互式卡片的形式显示。这些卡片会适配客户端的浅色或深色主题及语言。其他客户端则以文本形式显示相同的信息。

开发

npm install
npm run build       # server and widgets
npm test            # unit tests
npm run test:e2e    # both protocol versions over stdio and HTTP, against the build
npm run dev         # HTTP server on http://127.0.0.1:3000

HTTP 服务会使用 TIMESHEET_API_TOKEN 处理未携带凭据的请求，因此只要服务器可以从你的计算机外部访问，就请勿设置此变量。其他设置请参阅 .env.example。

故障排除

• 没有响应，或出现身份验证错误： 检查 TIMESHEET_API_TOKEN 是否已设置，且没有多余的空格或引号；同时确认该密钥仍存在于 Integrations > API Keys 中。
• 找不到命令： 使用 node --version 检查是否已安装 Node.js 20 或更高版本。
• 工具提示需要更高等级的套餐： MCP 服务需使用 Pro 套餐或更高级别的套餐。

许可证

MIT，详见 LICENSE.md。

支持

请在 github.com/timesheetIO/timesheet-mcp/issues 报告问题或提出想法。