Admin Toggl MCP

管理员Toggl MCP服务器

用于Toggl时间跟踪的模型上下文协议（MCP）服务器，具有高级管理级报告功能。

特性

基本时间跟踪

• 任务的开始时间跟踪
• 停止当前运行的时间条目
• 查看当前时间条目
• 列出可用工作区

高级管理员报告

• 带有KPI的组织仪表板
• 项目盈利能力分析
• 团队生产力报告
• 客户盈利能力分析
• 财务摘要
• 生产力洞察

安装

先决条件

• Python 3.12或更高版本
• Toggl API令牌

设置

1. 克隆存储库

   git clone 
   cd admin-toggl-mcp

1. 安装依赖项

   # Install uv if you haven't already
   curl -LsSf https://astral.sh/uv/install.sh | sh
   source $HOME/.local/bin/env

   # Install project dependencies
   uv sync

1. 获取Toggl API代币

- 首选 Toggl赛道 - 向下滚动至“API代币” - 复制您的令牌

1. 设置环境变量

   export TOGGL_API_TOKEN='your_api_token_here'

用法

运行服务器

# Run the server
uv run python server.py

# Or run with help
uv run python server.py --help

测试设置

# Run the test suite to verify everything is working
uv run python test_server.py

api参考

基本工具

start_tracking

开始跟踪新任务的时间。

参数：

• title （字符串，必填）：任务的标题/描述
• workspace_id （整数，可选）：工作区ID
• project_id （整数，可选）：项目ID
• tags （字符串数组，可选）：标签列表

stop_tracking

停止当前正在运行的时间条目。

show_current_time_entry

显示当前运行的时间条目（如果有的话）。

list_workspaces

列出所有可用的工作空间。

管理工具

get_organization_dashboard

获取包含KPI、工时、收入和利润指标的全面组织仪表板。

参数：

• workspace_id （整数，必填）：工作区ID
• start_date （字符串，可选）：开始日期（YYYY-MM-DD）
• end_date （字符串，可选）：结束日期（YYYY-MM-DD）
• period （字符串，可选）：预定义的时间段（周、月、季度、年）

get_project_profitability_analysis

获取详细的项目盈利能力分析，包括利润率、利用率和投资回报率。

参数：

• workspace_id （整数，必填）：工作区ID
• start_date （字符串，可选）：开始日期（YYYY-MM-DD）
• end_date （字符串，可选）：结束日期（YYYY-MM-DD）
• sort_by （字符串，可选）：排序标准（利润、收入、利润、小时数）
• min_hours （数字，可选）：纳入的最低小时阈值

get_team_productivity_report

获取包含利用率、性能指标和容量分析的团队生产力报告。

参数：

• workspace_id （整数，必填）：工作区ID
• start_date （字符串，可选）：开始日期（YYYY-MM-DD）
• end_date （字符串，可选）：结束日期（YYYY-MM-DD）
• include_individual_metrics （布尔值，可选）：包括单个员工指标

get_client_profitability_analysis

获取客户层面的盈利能力和收入分析。

参数：

• workspace_id （整数，必填）：工作区ID
• start_date （字符串，可选）：开始日期（YYYY-MM-DD）
• end_date （字符串，可选）：结束日期（YYYY-MM-DD）
• min_revenue （数字，可选）：最低收入门槛

get_financial_summary

获取收入、成本和利润趋势的高级财务摘要。

参数：

• workspace_id （整数，必填）：工作区ID
• period （字符串，可选）：分析周期（月、季度、年）
• compare_previous （布尔值，可选）：包括与上一期间的比较

get_productivity_insights

获取先进的生产力见解和时间跟踪模式。

参数：

• workspace_id （整数，必填）：工作区ID
• start_date （字符串，可选）：开始日期（YYYY-MM-DD）
• end_date （字符串，可选）：结束日期（YYYY-MM-DD）
• include_detailed_analysis （布尔值，可选）：包括详细的时间条目分析

建筑

核心组件

• main.py：使用MCP协议处理程序的主服务器实现
• toggl_api.py：Toggl跟踪API客户端以进行基本操作
• reports_api.py：用于高级分析的Toggl Reports API客户端
• models.py：工作区、时间条目和报告的数据模型
• admin_processor.py：管理员级报告的数据处理
• utils.py：用于数据解析和格式化的实用函数

数据模型

• TogglWorkspace：工作区信息
• TogglTimeEntry：时间输入数据
• ProjectProfitability：项目层面的盈利能力指标
• EmployeeProfitability：员工生产力指标
• ClientProfitability：客户层面的盈利能力分析
• OrganizationSummary：高级组织关键绩效指标

错误处理

该服务器包括全面的错误处理功能，用于：

• 网络连接问题
• API速率限制
• 身份验证失败
• 数据格式无效
• 缺少必填字段

发展

项目结构

admin-toggl-mcp/
├── src/
│   └── toggl_server/
│       ├── __init__.py
│       ├── main.py
│       ├── toggl_api.py
│       ├── reports_api.py
│       ├── admin_processor.py
│       ├── models.py
│       └── utils.py
├── server.py
├── test_server.py
├── pyproject.toml
└── README.md

运行测试

uv run python test_server.py

添加新功能

1. 向中添加新工具 handle_list_tools() 功能在 main.py
2. 在中实现工具处理程序 handle_call_tool()
3. 在中添加相应的数据模型 models.py 如有需要
4. 在中更新测试套件 test_server.py

故障排除

常见问题

1. “需要TOGGL_API_TOKEN环境变量”

- 确保您已正确设置环境变量 - 验证您的API令牌是否有效

1. “身份验证失败”

- 检查您的API令牌是否正确 - 确保您的Toggl帐户处于活动状态

1. “超出费率限制”

- 请稍等片刻，然后再提出更多请求 - 服务器自动处理速率限制

1. 导入错误

- 跑 uv sync 确保所有依赖项都已安装 - 检查您是否使用Python 3.12或更高版本

获取帮助

如果您遇到问题：

1. 运行测试套件： uv run python test_server.py
2. 检查日志以了解详细的错误消息
3. 验证Toggl API令牌是否可以使用简单的curl请求

许可证

该项目根据MIT许可证获得许可。

贡献

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