使用说明

TimeCamp MCP服务器

一个模型上下文协议（MCP）服务器，将TimeCamp时间跟踪直接集成到Claude、Cline和Continue等人工智能助手中。

特性

⏱️ 实时定时器控制 -启动、停止和检查计时器状态
📊 时间录入管理 -为过去的工作创建手动时间条目
🔍 智能搜索 -跨项目和任务的模糊搜索
📈 报告 -每日总结、每周报告和时间跟踪见解
🚀 智能高速缓存 -内置缓存管理，响应时间快
📝 丰富提示 -预先构建的站立报告和分析提示

快速开始

先决条件

具有API访问权限的TimeCamp帐户
MCP兼容客户端（Claude Desktop、Cline、Continue等）
紫外线已安装（MCP客户端要求）

获取您的TimeCamp API代币

登录到夏令营
引导到 个人资料
向下滚动至 您的编程API令牌
复制您的API令牌

安装

只需将TimeCamp MCP服务器添加到您的客户端配置中即可。服务器将在需要时自动从PyPI下载。

客户端配置

克劳德桌面

增添 ~/.claude/claude_desktop_config.json （macOS/Linux）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "timecamp": {
      "command": "uvx",
      "args": ["timecamp-mcp-server"],
      "env": {
        "TIMECAMP_API_TOKEN": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

VS代码（点击、继续等）

对于支持MCP的VS Code扩展，请添加到您的设置中：

{
  "cline.mcp.servers": {
    "timecamp": {
      "command": "uvx",
      "args": ["timecamp-mcp-server"],
      "env": {
        "TIMECAMP_API_TOKEN": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

替代方案：手动安装

如果您更喜欢从源代码安装：

git clone https://github.com/kkeeling/timecamp-mcp-server.git
cd timecamp-mcp-server

然后使用此配置：

{
  "mcpServers": {
    "timecamp": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/timecamp-mcp-server",
        "run",
        "python",
        "timecamp-server.py"
      ],
      "env": {
        "TIMECAMP_API_TOKEN": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

资源

资源提供对TimeCamp数据的只读访问：

`timecamp://projects`

列出所有可用项目及其任务计数和状态。

示例响应:

{
  "projects": [
    {
      "id": 12345,
      "name": "Website Development",
      "color": "#4CAF50",
      "tasks_count": 15,
      "archived": false
    }
  ],
  "total_count": 8,
  "include_archived": true
}

`timecamp://tasks`

列出所有任务及其关联项目。

示例响应:

[
  {
    "id": 67890,
    "name": "Frontend Development",
    "project_id": 12345,
    "project_name": "Website Development",
    "archived": false
  }
]

`timecamp://timer`

显示当前计时器状态。

示例响应:

{
  "is_running": true,
  "task_name": "Code Review",
  "task_id": 67890,
  "timer_id": 11111,
  "project_name": "Website Development",
  "elapsed_time": "1h 23m",
  "elapsed_seconds": 4980,
  "start_time": "2024-01-15T10:30:00Z"
}

`timecamp://time-entries/{date}`

检索特定日期的时间条目（格式：YYYY-MM-DD）。

示例: timecamp://time-entries/2024-01-15

示例响应:

{
  "date": "2024-01-15",
  "total_time": "6h 45m",
  "total_seconds": 24300,
  "entries": [
    {
      "task_name": "Code Review",
      "task_id": 67890,
      "project_name": "Website Development",
      "duration": "2h 30m",
      "duration_seconds": 9000,
      "notes": ["Reviewed PR #123", "Fixed merge conflicts"]
    }
  ],
  "entry_count": 4,
  "is_timer_running": true,
  "current_task": "Documentation",
  "current_task_id": 67891
}

`timecamp://changes`

跟踪最近的状态变化（计时器启动/停止、创建的条目）。

示例响应:

{
  "changes": [
    {
      "type": "timer_started",
      "timestamp": "2024-01-15T14:30:00Z",
      "details": {
        "task_id": 67890,
        "task_name": "Code Review",
        "timer_id": 11111
      }
    }
  ],
  "timestamp": "2024-01-15T14:35:00Z"
}

`timecamp://search/{query}`

按名称模糊搜索项目和任务。

示例: timecamp://search/frontend

响应:

{
  "results": [
    {
      "type": "task",
      "id": 67890,
      "name": "Frontend Development",
      "match_score": 0.95,
      "project_name": "Website Development"
    },
    {
      "type": "project",
      "id": 12345,
      "name": "Frontend Redesign",
      "match_score": 0.85
    }
  ],
  "total_results": 2,
  "query": "frontend"
}

工具

工具允许您在TimeCamp中执行操作：

`start_timer`

为特定任务启动计时器。

参数:

task_id （必填）：要跟踪的任务的ID
note （可选）：附在计时器上的注释

示例:

{
  "task_id": 67890,
  "note": "Working on authentication feature"
}

响应:

{
  "message": "Timer started for task 'Frontend Development'",
  "timer_id": 11111,
  "task_id": 67890,
  "task_name": "Frontend Development",
  "started_at": "2024-01-15T10:30:00Z",
  "project_name": "Website Development"
}

`stop_timer`

停止当前正在运行的计时器。

参数：无

响应:

{
  "message": "Timer stopped",
  "duration": "2h 15m",
  "duration_seconds": 8100,
  "task_name": "Frontend Development",
  "task_id": 67890,
  "timer_id": 11111
}

`create_time_entry`

为过去的工作创建手动时间条目。

参数:

task_id （必填）：任务ID
date （必填）：YYYY-MM-DD格式的日期
start_time （必填）：HH:MM格式的开始时间
end_time （必填）：HH:MM格式的结束时间
note （可选）：已完成工作的描述

示例:

{
  "task_id": 67890,
  "date": "2024-01-14",
  "start_time": "14:00",
  "end_time": "16:30",
  "note": "Implemented user authentication"
}

响应:

{
  "entry_id": 99999,
  "task_id": 67890,
  "task_name": "Frontend Development",
  "project_name": "Website Development",
  "date": "2024-01-14",
  "start_time": "14:00",
  "end_time": "16:30",
  "duration": "2h 30m",
  "duration_seconds": 9000,
  "note": "Implemented user authentication"
}

提示

常见时间跟踪工作流的预构建提示：

`daily_standup_prompt`

根据时间条目生成每日站立报告。

参数:

date （可选）：YYYY-MM-DD格式的日期（默认为今天）

输出示例:

Daily Standup for 2024-01-15
==============================
Total time tracked: 6h 45m

What I worked on:
• Frontend Development (Website Development): 2h 30m - Implemented auth flow; Fixed responsive issues
• Code Review (Website Development): 1h 45m - Reviewed PR #123
• Documentation (API Project): 1h 30m - Updated API docs
• Team Meeting (Internal): 1h 0m

Currently working on: Documentation

`weekly_report_prompt`

生成全面的每周时间报告。

参数:

start_date （可选）：YYYY-MM-DD格式的开始日期（默认为本周的星期一）

输出示例:

Weekly Time Report
Week of 2024-01-08
========================================
Total time tracked: 35h 20m

Time by Day:
• Monday (2024-01-08): 7h 15m
• Tuesday (2024-01-09): 6h 45m
• Wednesday (2024-01-10): 7h 30m
• Thursday (2024-01-11): 8h 0m
• Friday (2024-01-12): 5h 50m

Time by Project:
• Website Development: 22h 15m
• API Project: 8h 30m
• Internal: 4h 35m

Top 5 Tasks:
• Frontend Development (Website Development): 12h 30m
• Backend API (API Project): 6h 45m
• Code Review (Website Development): 5h 15m
• Documentation (API Project): 3h 30m
• Team Meeting (Internal): 2h 45m

`time_tracking_insights_prompt`

为更好的时间跟踪提供见解和建议。

参数：无

输出示例:

Time Tracking Insights
==============================

Today's tracked time: 4h 30m
Tasks worked on: 3

Timer is running: Documentation
Elapsed time: 45m

Yesterday's total: 7h 15m
Tasks completed: 5
📊 You're tracking less time than yesterday.

Suggestions:
• Review untracked time gaps
• Set reminders to start/stop timers
• Use descriptive notes for better reporting

使用示例

开始跟踪时间

"Start timer for task 67890 with note 'Working on login feature'"
"Begin tracking Frontend Development task"
"Start working on task ID 12345"

停止跟踪

"Stop the timer"
"Stop tracking time"
"End current timer"

检查状态

"What's my current timer status?"
"Am I tracking time right now?"
"Show current timer"

创建时间条目

"Log 2 hours for task 67890 yesterday from 2pm to 4pm"
"Create time entry for Frontend Development on 2024-01-14 from 09:00 to 11:30"
"Add manual entry for task 12345"

查看摘要

"Show me today's time tracking"
"What did I work on today?"
"Generate my daily standup"
"Create weekly report for last week"
"Show time tracking insights"

高级功能

智能高速缓存

项目和任务的5分钟TTL缓存
状态更改时自动缓存失效
ETag支持高效的资源更新

错误处理

优雅地处理API错误
清除常见问题的错误消息
速率限制检测和警告

状态跟踪

监控定时器的启动/停止
跟踪时间条目创建
通过以下方式提供更改历史记录 timecamp://changes 资源

环境变量

变量	描述	必填
`TIMECAMP_API_TOKEN`	您的TimeCamp API代币	是

故障排除

“未设置TIMECAMP_API_TOKEN环境变量”

确保在MCP客户端的配置文件中正确配置了API令牌。

“API令牌无效”

在TimeCamp中验证您的令牌： 个人资料→ API访问
检查令牌中是否有多余的空格或字符
确保令牌尚未重新生成

“超出费率限制”

API TimeCamp有费率限制。等待60秒后重试。

定时器未启动

验证任务ID是否存在
检查计时器是否已在运行（先停止）
确保任务未存档

发展

服务器被实现为一个单文件Python脚本(timecamp-server.py)它使用PEP 723内联脚本元数据。依赖关系由UV自动处理。

在本地运行

# Using UV
uv run timecamp-server.py

依赖项

fastmcp -MCP服务器框架
httpx -异步HTTP客户端
pydantic -数据验证
rapidfuzz -模糊字符串匹配
python-dotenv -环境变量管理

贡献

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

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

API TimeCamp文档: https://developer.timecamp.com/
MCP文件: https://modelcontextprotocol.io/

使用说明

TimeCamp MCP服务器

特性

快速开始

先决条件

获取您的TimeCamp API代币

安装

客户端配置

克劳德桌面

VS代码（点击、继续等）

替代方案：手动安装

资源

timecamp://projects

timecamp://tasks

timecamp://timer

timecamp://time-entries/{date}

timecamp://changes

timecamp://search/{query}

工具

start_timer

stop_timer

create_time_entry

提示

daily_standup_prompt

weekly_report_prompt

time_tracking_insights_prompt

使用示例

开始跟踪时间

停止跟踪

检查状态

创建时间条目

查看摘要

高级功能

智能高速缓存

错误处理

状态跟踪

环境变量

故障排除

“未设置TIMECAMP_API_TOKEN环境变量”

“API令牌无效”

“超出费率限制”

定时器未启动

发展

在本地运行

依赖项

贡献

许可证

支持

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

科学研究的开源MCP服务器

`timecamp://projects`

`timecamp://tasks`

`timecamp://timer`

`timecamp://time-entries/{date}`

`timecamp://changes`

`timecamp://search/{query}`

`start_timer`

`stop_timer`

`create_time_entry`

`daily_standup_prompt`

`weekly_report_prompt`

`time_tracking_insights_prompt`