KIMAI MCP服务器

一种模型上下文协议（MCP）服务器基迈2 时间跟踪应用程序。此服务器允许大型语言模型进行交互 KIMAI用于时间跟踪、项目管理和报告。

特性

时间跟踪

开始/停止时间条目：实时跟踪开始和结束时间
创建时间条目：添加具有自定义开始/结束时间的历史时间条目
更新时间条目：修改现有条目（时间、描述、标签）
删除时间条目：删除不正确或重复的条目
查询时间条目：按项目、活动、客户、用户、日期范围和状态搜索和筛选时间表

项目与活动管理

列出项目和活动：浏览可用的项目和活动
创建项目：在客户下建立新项目
创建活动：定义新的工作类型（全局或项目特定）
更新项目和活动：修改名称、可见性、计费状态和颜色

客户管理

列出客户：查看所有客户
创建客户：添加具有货币偏好的新客户
更新客户：修改客户信息和设置

报告和分析

时间表摘要：生成包含总小时数、计费时间和非计费时间的报告
项目分解：查看项目之间的时间分布
活动分析：分析花在不同活动类型上的时间
灵活过滤：按用户、客户、项目、活动和日期范围筛选报告

先决条件

基迈2：正在运行的KIMAI 2实例（2.0或更高版本）
python：Python 3.10或更高版本
API代币：KIMAI用户资料中的承载令牌

安装

快速设置（推荐）

克隆或下载此存储库：

   cd /projects/personal/kimai-mcp

运行安装脚本：

   ./setup.sh

编辑 .env 文件中包含您的KIMAI凭据：

   nano .env  # or use your preferred editor

测试连接：

   source .venv/bin/activate
   python3 test_connection.py

手动设置

使用uv安装依赖项：

   uv venv
   uv pip install -r requirements.txt

配置环境变量：

   cp .env.example .env
   # Edit .env with your KIMAI URL and API token

生成KIMAI API令牌

登录您的KIMAI实例
导航到：用户配置文件>API
点击“创建新令牌”
复制令牌并将其添加到您的 .env 文件

配置

环境变量

服务器需要两个环境变量：

变量	描述	示例
`KIMAI_BASE_URL`	KIMAI实例的基本URL	`http://localhost:8001`
`KIMAI_API_TOKEN`	API身份验证的承载令牌	``

Claude代码配置

要将此MCP服务器与Claude Code（CLI）一起使用，请将其添加到MCP设置文件中。

地点： ~/.claude/mcp_settings.json 或者你的项目 .claude/mcp_settings.json

添加以下配置：

{
  "mcpServers": {
    "kimai": {
      "command": "/projects/personal/kimai-mcp/.venv/bin/python",
      "args": ["/projects/personal/kimai-mcp/server.py"],
      "env": {
        "KIMAI_BASE_URL": "http://localhost:8001",
        "KIMAI_API_TOKEN": ""
      }
    }
  }
}

重要提示：

对两者都使用绝对路径 command 和 args
替换 /projects/personal/kimai-mcp 使用您的实际安装路径
替换 `` 使用您的KIMAI API代币
Python二进制文件应指向您的虚拟环境

添加配置后，重新启动Claude Code以加载MCP服务器。您可以通过检查KIMAI相关工具来验证它是否已加载。

Claude桌面配置

将此MCP服务器添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
	"kimai": {
	  "command": "/projects/personal/kimai-mcp/.venv/bin/python",
	  "args": ["/projects/personal/kimai-mcp/server.py"],
	  "env": {
		"KIMAI_BASE_URL": "http://localhost:8001",
		"KIMAI_API_TOKEN": "your_api_token_here"
	  }
	}
  }
}

注：确保使用绝对路径并指向虚拟环境中的Python二进制文件。

可用工具

时间表工具

`list_timesheets`

列出带有筛选选项的时间表条目。

参数：

user （可选）：按用户ID筛选
customer （可选）：按客户ID筛选
project （可选）：按项目ID筛选
activity （可选）：按活动ID筛选
active （可选）：仅用于运行时间表的筛选器
exported （可选）：按导出状态筛选
begin （可选）：开始日期过滤器（ISO 8601）
end （可选）：结束日期过滤器（ISO 8601）
page （默认值：1）：分页页码
size （默认值：50）：每页显示结果（最多100个）
format （默认：“json”）：响应格式（“json”或“markdown”）

例子：

List all running timesheets
Show me timesheets for project 1 from last week

`get_timesheet`

获取特定时间表的详细信息。

参数：

id：时间表ID（必填）
format：响应格式（“json”或“markdown”）

例子：

Get details for timesheet #1245

`start_timesheet`

开始跟踪项目和活动的时间。

参数：

project：项目ID（必填）
activity：活动ID（必填）
description （可选）：工作描述
tags （可选）：逗号分隔的标签

例子：

Start tracking time for project 1, activity 355
Start timer for "Code Review" on project 2

`stop_timesheet`

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

参数：

id：要停止的时间表ID（必需）

例子：

Stop timesheet #1245

`create_timesheet`

创建具有特定开始/结束时间的时间条目。

参数：

project：项目ID（必填）
activity：活动ID（必填）
begin：以ISO 8601格式开始日期时间（必需）
end （可选）：结束日期时间（运行条目省略）
description （可选）：工作描述
tags （可选）：逗号分隔的标签

例子：

Create a timesheet for yesterday from 9am to 5pm on project 1, activity 355
Log 3 hours of work for project 2, activity 10

`update_timesheet`

更新现有时间表条目。

参数：

id：时间表ID（必填）
begin （可选）：新开始日期时间
end （可选）：新结束日期时间
description （可选）：更新的描述
tags （可选）：更新标签

例子：

Update timesheet #1245 with description "Fixed bug in authentication"
Change the end time of timesheet #1244 to 6pm

`delete_timesheet`

删除时间表条目。

参数：

id：时间表ID（必填）

例子：

Delete timesheet #1245

项目工具

`list_projects`

列出所有经过筛选的项目。

参数：

customer （可选）：按客户ID筛选
visible （可选）：按可见性过滤
page （默认值：1）：页码
size （默认值：50）：每页结果
format （默认：“json”）：响应格式

例子：

List all projects
Show me projects for customer 1

`get_project`

获取特定项目的详细信息。

参数：

id：项目ID（必填）
format：响应格式

例子：

Get details for project #1

`create_project`

创建一个新项目。

参数：

name：项目名称（必填）
customer：客户ID（必填）
visible （默认值：true）：可见性
billable （默认值：true）：计费状态
color （可选）：十六进制颜色代码

例子：

Create a new project "Website Redesign" for customer 1

`update_project`

更新项目的详细信息。

参数：

id：项目ID（必填）
name （可选）：新名称
visible （可选）：新可见性
billable （可选）：新的计费状态
color （可选）：新颜色

例子：

Rename project #1 to "Mobile App Development"
Make project #2 non-billable

活动工具

`list_activities`

列出所有活动。

参数：

project （可选）：按项目ID筛选
visible （可选）：按可见性过滤
page （默认值：1）：页码
size （默认值：50）：每页结果
format （默认：“json”）：响应格式

例子：

List all activities
Show activities for project 1

`get_activity`

获取特定活动的详细信息。

参数：

id：活动ID（必填）
format：响应格式

例子：

Get details for activity #355

`create_activity`

创建新活动。

参数：

name：活动名称（必填）
project （可选）：项目ID（全局省略）
visible （默认值：true）：可见性
billable （默认值：true）：计费状态
color （可选）：十六进制颜色代码

例子：

Create a new activity called "Code Review"
Create a global activity "Meeting"

`update_activity`

更新活动的详细信息。

参数：

id：活动ID（必填）
name （可选）：新名称
visible （可选）：新可见性
billable （可选）：新的计费状态
color （可选）：新颜色

例子：

Rename activity #355 to "Senior Code Review"

客户工具

`list_customers`

列出所有客户。

参数：

visible （可选）：按可见性过滤
page （默认值：1）：页码
size （默认值：50）：每页结果
format （默认：“json”）：响应格式

例子：

List all customers

`get_customer`

获取特定客户的详细信息。

参数：

id：客户ID（必填）
format：响应格式

例子：

Get details for customer #1

`create_customer`

创建新客户。

参数：

name：客户名称（必填）
currency （默认值：“USD”）：3个字母的货币代码
visible （默认值：true）：可见性
billable （默认值：true）：计费状态
color （可选）：十六进制颜色代码

例子：

Create a new customer "Acme Corporation" with EUR currency

`update_customer`

更新客户的详细信息。

参数：

id：客户ID（必填）
name （可选）：新名称
currency （可选）：新货币
visible （可选）：新可见性
billable （可选）：新的计费状态
color （可选）：新颜色

例子：

Change customer #1 currency to CAD

报告工具

`get_timesheet_summary`

生成时间表数据的摘要报告。

参数：

user （可选）：按用户ID筛选
customer （可选）：按客户ID筛选
project （可选）：按项目ID筛选
activity （可选）：按活动ID筛选
begin （可选）：开始日期（ISO 8601）
end （可选）：结束日期（ISO 8601）
format （默认：“markdown”）：响应格式

例子：

Generate a timesheet report for this week
Show me total hours for project 1 this month
Summary of all billable hours for customer 1

用法示例

时间跟踪工作流

User: Start tracking time for the FNLR project
Claude: [Uses list_projects to find "First Nations Land Register"]
        [Uses list_activities to find appropriate activity]
        [Uses start_timesheet with project=1, activity=355]

User: Stop the timer
Claude: [Uses list_timesheets with active=true to find running entry]
        [Uses stop_timesheet with the ID]

User: Add a description "Implemented authentication feature"
Claude: [Uses update_timesheet to add description]

报告工作流

User: How much time did I spend on project 1 this week?
Claude: [Uses get_timesheet_summary with project=1, date filters]
        [Returns markdown report with breakdown]

User: Show me all my timesheets from yesterday
Claude: [Uses list_timesheets with date filters, format=markdown]
        [Returns formatted list of entries]

项目设置工作流

User: Create a new customer "Acme Corp" and project "Website Redesign"
Claude: [Uses create_customer with name="Acme Corp"]
        [Uses create_project with the new customer ID]
        [Uses create_activity for common tasks]

User: What activities are available for this project?
Claude: [Uses list_activities with the new project ID]

响应格式

服务器支持两种响应格式：

JSON格式

结构化数据是程序化处理的理想选择：

{
  "id": 1245,
  "project": 1,
  "activity": 355,
  "begin": "2025-11-05T15:36:00+0100",
  "end": "2025-11-05T18:10:00+0100",
  "duration": 9240
}

Markdown格式

适合报告和摘要的人类可读格式：

## Timesheet #1245

**Status:** ✓ Completed
**Project ID:** 1
**Activity ID:** 355
**Duration:** 2.57 hours (9240 seconds)

错误处理

服务器提供清晰、可操作的错误消息：

身份验证错误：检查您的API令牌
未发现错误：验证ID是否存在
验证错误：查看参数格式
网络错误：验证KIMAI URL是否可访问

所有错误都包括解决建议。

发展

测试服务器

# Set environment variables
export KIMAI_BASE_URL=http://localhost:8001
export KIMAI_API_TOKEN=your_token

# Run the server directly (will wait for stdio input)
python server.py

项目结构

kimai-mcp/
├── server.py           # Main MCP server implementation
├── requirements.txt    # Python dependencies
├── .env.example       # Environment variable template
└── README.md          # This file

故障排除

服务器无法启动

检查Python版本（需要3.10+）
验证是否安装了所有依赖项： pip install -r requirements.txt
确保设置了环境变量

API错误

验证KIMAI实例是否正在运行且可访问
检查API令牌是否有效（未过期）
确保令牌具有适当的权限

空结果

检查过滤器是否过于严格
验证KIMAI中是否存在数据
先尝试不使用过滤器

贡献

欢迎投稿！请确保：

代码遵循Python最佳实践
Pydantic模型验证所有输入
错误信息清晰且可操作
文档已更新

许可证

这个项目是开源的，可以在MIT许可证下使用。

支持

对于问题或疑问：

KIMAI文件：https://www.kimai.org/documentation/
MCP文件：https://modelcontextprotocol.io/

更新日志

v1.0.0（2025-11-06）

初始版本
完整时间表管理（CRUD操作）
项目、活动和客户管理
摘要报告和分析
支持JSON和Markdown响应格式
全面的错误处理

Kimai MCP

快速接入

详细介绍

KIMAI MCP服务器

特性

时间跟踪

项目与活动管理

客户管理

报告和分析

先决条件

安装

快速设置（推荐）

手动设置

生成KIMAI API令牌

配置

环境变量

Claude代码配置

Claude桌面配置

可用工具

时间表工具

list_timesheets

get_timesheet

start_timesheet

stop_timesheet

create_timesheet

update_timesheet

delete_timesheet

项目工具

list_projects

get_project

create_project

update_project

活动工具

list_activities

get_activity

create_activity

update_activity

客户工具

list_customers

get_customer

create_customer

update_customer

报告工具

get_timesheet_summary

用法示例

时间跟踪工作流

报告工作流

项目设置工作流

响应格式

JSON格式

Markdown格式

错误处理

发展

测试服务器

项目结构

故障排除

服务器无法启动

API错误

空结果

贡献

许可证

支持

更新日志

v1.0.0（2025-11-06）

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`list_timesheets`

`get_timesheet`

`start_timesheet`

`stop_timesheet`

`create_timesheet`

`update_timesheet`

`delete_timesheet`

`list_projects`

`get_project`

`create_project`

`update_project`

`list_activities`

`get_activity`

`create_activity`

`update_activity`

`list_customers`

`get_customer`

`create_customer`

`update_customer`

`get_timesheet_summary`