使用说明

项目简介

mcp-nokotime 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在桥接 Noko 时间跟踪服务与支持 MCP 协议的客户端，如 Claude Desktop。通过此服务器，用户可以使用 Claude Desktop 等工具，以自然语言指令调用 Noko 的功能，例如查询时间记录、创建新的时间条目、列出项目和用户等，从而提升工作效率。

主要功能点

Noko API v2 全面集成: 完整支持 Noko API v2 版本的所有功能。
安全认证处理: 安全地处理 Noko API 的身份验证。
时间条目管理: 支持创建、查询和管理 Noko 中的时间记录。
项目和用户列表: 可以获取 Noko 中项目和用户的列表信息。
错误处理和验证: 提供完善的错误处理和输入验证机制。
异步支持: 使用 async/await 技术，提供高效的异步操作支持。

安装步骤

安装 Python 3.9+: 确保您的系统已安装 Python 3.9 或更高版本。

克隆仓库: 使用 git 命令克隆 mcp-nokotime 仓库到本地：

git clone https://github.com/Lullabot/mcp-nokotime.git
cd mcp-nokotime

安装 uv (可选): uv 是一个快速的 Python 包安装和虚拟环境管理工具，如果尚未安装，请运行以下命令安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

创建并激活虚拟环境: 创建并激活 Python 虚拟环境，以隔离项目依赖：

uv venv
source .venv/bin/activate  # 在 Unix/macOS 系统上
# 或
.venv\Scripts\activate  # 在 Windows 系统上

安装项目依赖: 使用 uv 或 pip 安装项目依赖（开发模式）：

uv pip install -e .
# 或
pip install -e .

测试服务器: 运行以下命令测试服务器是否正常启动：

python -m nokotime.server

服务器配置

要将 mcp-nokotime 服务器配置到 MCP 客户端（例如 Claude Desktop），您需要提供服务器的启动命令和参数。以下是 Claude Desktop 客户端的配置示例，您需要根据您的实际环境进行调整。

Claude Desktop 配置 (claude_desktop_config.json):

{
  "mcpServers": {
    "noko": {  // 服务器名称，客户端用此名称引用
      "command": "/path/to/your/mcp-nokotime/.venv/bin/python3",  // Python 解释器路径，请替换为您的虚拟环境中的 Python 路径
      "args": [
        "-m",
        "nokotime.server"  // 启动服务器的模块和脚本
      ],
      "env": {
        "NOKO_API_TOKEN": "YOUR_NOKO_API_TOKEN",  // 您的 Noko API 令牌，请替换为您的实际令牌
        "PYTHONPATH": "/path/to/your/mcp-nokotime"  // mcp-nokotime 项目根目录路径，请替换为您的实际路径
      }
    }
  }
}

配置说明:

'"noko"': MCP 服务器的名称，您可以在 Claude Desktop 中使用这个名称来引用该服务器。
'"command"': 启动 MCP 服务器的命令。这里指向您在虚拟环境中安装的 Python 解释器。请务必替换为您的实际 Python 路径。
'"args"': 启动命令的参数。'"-m nokotime.server"' 表示运行 'nokotime' 包中的 'server.py' 模块。
'"env"': 环境变量配置。
- '"NOKO_API_TOKEN"': 必须配置您的 Noko API 令牌，用于服务器访问 Noko API。请从 Noko 服务获取您的 API 令牌并替换 '"YOUR_NOKO_API_TOKEN"'。请勿使用示例值，务必使用您自己的令牌。
- '"PYTHONPATH"': 指定 Python 模块搜索路径，确保 Python 可以找到 'nokotime' 包。请务必替换为您的 mcp-nokotime 项目的实际根目录路径。

重要提示:

路径替换: 请根据您的实际安装路径，准确替换 'command' 和 'env.PYTHONPATH' 中的路径。
API 令牌: 请务必配置正确的 'NOKO_API_TOKEN' 环境变量，否则服务器将无法连接到 Noko API。
重启客户端: 修改 'claude_desktop_config.json' 后，需要重启 Claude Desktop 客户端 才能使配置生效。
检查日志: 如果遇到连接问题，请检查 Claude Desktop 的 MCP 日志文件 ('~/Library/Logs/Claude/mcp*.log' 或 '%APPDATA%\Claude\mcp*.log') 以获取详细错误信息。

基本使用方法

配置完成后，在 Claude Desktop 或其他支持 MCP 协议的客户端中，您可以使用自然语言指令来调用 mcp-nokotime 服务器提供的工具。

可用工具:

List Time Entries (列出时间条目): 查询时间记录。
- 示例参数: '{"from": "2023-12-01", "to": "2023-12-31", "user_ids": [123], "project_ids": [456]}'
- 描述: 列出指定日期范围内，特定用户和项目的时间条目。
Create Time Entry (创建时间条目): 创建新的时间记录。
- 示例参数: '{"date": "2023-12-14", "minutes": 60, "description": "Working on project documentation", "project_id": 123}'
- 描述: 创建一个新的时间条目，包括日期、时长、描述和项目 ID。
List Projects (列出项目): 查询项目列表。
- 示例参数: '{"state": "active"}'
- 描述: 列出所有项目，可以根据状态 (active, archived, all) 进行过滤。
List Users (列出用户): 查询用户列表。
- 示例参数: '{"state": "active"}'
- 描述: 列出所有用户，可以根据状态 (active, suspended, all) 进行过滤。

您可以在 Claude Desktop 中使用自然语言指令，结合上述工具和参数，与 Noko 时间跟踪服务进行交互。例如，您可以询问 "列出我今天在项目 XYZ 上的时间记录" 或 "为项目 ABC 创建一个 30 分钟的时间记录，描述为 '会议讨论'"。客户端会将您的指令转换为对 mcp-nokotime 服务器的工具调用，并返回 Noko 的数据或执行相应的操作。

关键词