项目简介 Kimai时间追踪MCP服务器是一个基于Model Context Protocol (MCP) 构建的后端应用，旨在作为Anthropic Claude Desktop等LLM（大型语言模型）客户端与您的公司Kimai时间追踪系统之间的桥梁。它允许LLM直接访问和管理Kimai中的活动、项目和时间表数据，从而实现更智能、更高效的工作流自动化和信息查询。

主要功能点

Kimai连接状态检查: 验证与Kimai API的连接和认证状态。
Kimai版本查询: 获取当前Kimai服务器的版本信息。
项目管理:
- 列出所有项目，可按关键词、客户或可见性进行过滤。
活动管理:
- 列出所有活动，可按关键词、项目或可见性进行过滤。
- 根据ID获取特定活动的详细信息。
- 创建新的活动。
- 更新现有活动的属性。
- 设置或更新活动上的元字段值。
上下文数据缓存: 自动下载并缓存最新的活动、客户、标签、时间表和项目信息到本地，以提高查询效率。
会话管理与安全: 通过Docker secrets安全存储凭据，在容器内以非root用户运行，且不记录敏感数据，所有API通信均使用HTTPS。

安装步骤

准备环境:
- 安装Docker Desktop并确保已启用MCP Toolkit。
- 安装Docker MCP CLI插件 ('docker mcp')。
- 在Kimai系统中生成一个有效的API令牌。
构建服务器镜像:
- 创建一个名为 'kimai-mcp-server' 的目录，并将项目中的 'Dockerfile', 'requirements.txt', 'kimai_server.py' 等文件放入其中。
- 在 'kimai-mcp-server' 目录下运行Docker构建命令：
```
docker build -t kimai-mcp-server .
```

配置敏感信息:

使用Docker MCP CLI安全地设置您的Kimai API凭据：

docker mcp secret set KIMAI_USER="您的Kimai用户名"
docker mcp secret set KIMAI_TOKEN="您的Kimai API令牌"
docker mcp secret set KIMAI_BASE_URL="您的Kimai API基础URL（例如：https://kimai.yourcompany.com.mx）"

您可以通过 'docker mcp secret list' 命令查看已设置的密钥。

添加自定义MCP服务器目录条目:

在您的Docker MCP配置路径 ('~/.docker/mcp/catalogs/') 下创建一个名为 'custom.yaml' 的文件（如果不存在）。

将以下YAML配置添加到 'custom.yaml' 文件中，定义您的Kimai MCP服务器：

version: 2
name: custom
displayName: 自定义MCP服务器
registry:
  kimai:
    description: "管理和列出Kimai的活动和项目"
    title: "Kimai"
    type: server
    dateAdded: "2025-10-12T00:00:00Z" # 请根据实际添加日期修改
    image: kimai-mcp-server:latest
    ref: ""
    tools:
      - name: kimai_ping
      - name: kimai_version
      - name: kimai_list_projects
      - name: kimai_list_activities
      - name: kimai_get_activity
      - name: kimai_create_activity
      - name: kimai_update_activity
      - name: kimai_set_activity_meta
    secrets:
      - name: KIMAI_USER
        env: KIMAI_USER
        example: "john.doe"
      - name: KIMAI_TOKEN
        env: KIMAI_TOKEN
        example: "kT-xxxxxxxxxxxxxxxxxxxx"
      - name: KIMAI_BASE_URL
        env: KIMAI_BASE_URL
        example: "https://kimai.mindfactory.com.mx"
    metadata:
      category: integration
      tags:
        - kimai
        - time-tracking
        - activities
        - projects
      license: MIT
      owner: local

服务器配置 (供MCP客户端使用)

当您的MCP客户端（如Claude Desktop）需要连接此Kimai MCP服务器时，它需要以下配置信息：

{
  "server name": "Kimai-MCP",
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "--env",
    "MCP_HTTP_TRANSPORT=stdio",
    "kimai-mcp-server:latest"
  ],
  "description": "连接到您的Kimai时间追踪系统，管理活动、项目和时间表。需要配置KIMAI_USER、KIMAI_TOKEN和KIMAI_BASE_URL作为Docker Secret。",
  "tags": [
    "时间追踪",
    "项目管理",
    "活动管理",
    "企业集成"
  ]
}

参数注释:

'server name': MCP服务器的唯一标识名称。
'command': 启动MCP服务器的命令，这里是'docker'命令。
'args': 传递给'command'的参数列表。
- '--rm': 容器退出时自动移除。
- '-i': 保持标准输入（stdin）打开，允许MCP客户端通过stdin/stdout进行通信。
- '--env MCP_HTTP_TRANSPORT=stdio': 指定MCP服务器使用标准输入输出（stdio）作为传输协议。
- 'kimai-mcp-server:latest': 使用您之前构建的Docker镜像名称及其标签。
'description': 服务器功能的简要说明。
'tags': 描述服务器功能的关键词列表。

基本使用方法 配置完成后，您可以在支持MCP协议的LLM客户端中通过自然语言请求来使用此服务器提供的功能。例如：

检查连接:
- "Kimai，帮我ping一下服务。" (调用 'kimai_ping' 工具)
- "Kimai，当前版本是多少？" (调用 'kimai_version' 工具)
查询项目:
- "Kimai，列出所有包含'客户'字样的项目。" (调用 'kimai_list_projects' 工具，参数 'term="客户"')
- "Kimai，显示客户ID为3的所有可见项目。" (调用 'kimai_list_projects' 工具，参数 'customer="3" visible="1"')
查询活动:
- "Kimai，显示所有包含'会议'字样的活动。" (调用 'kimai_list_activities' 工具，参数 'term="会议"')
- "Kimai，列出项目ID为42的所有活动。" (调用 'kimai_list_activities' 工具，参数 'project="42"')
管理活动:
- "Kimai，为项目42创建一个名为'内部评审'的新活动。" (调用 'kimai_create_activity' 工具，参数 'name="内部评审" project="42"')
- "Kimai，更新ID为85的活动，将其名称改为'客户电话'。" (调用 'kimai_update_activity' 工具，参数 'id="85" name="客户电话"')
- "Kimai，将ID为85的活动的元字段'priority'设置为'high'。" (调用 'kimai_set_activity_meta' 工具，参数 'id="85" meta_name="priority" meta_value="high"')

关键词

信息