关键词

时间跟踪QuickBooks TimeAPI集成数据访问业务报表

使用说明

项目简介

本项目 'qb-time-mcp-server' 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为大型语言模型（LLM）客户端提供访问 QuickBooks Time (原TSheets) API 的能力。通过此服务器，LLM 可以调用预定义的工具来获取 QuickBooks Time 中的各种数据，例如工单代码、时间表、用户、项目和报表等，从而实现与时间跟踪数据的智能交互。

主要功能点

  • 数据访问工具: 提供丰富的工具集，允许 LLM 客户端查询和检索 QuickBooks Time 中的核心数据，包括：
    • 工单代码 (Job Codes): 获取详细的工单信息，支持多种过滤条件，例如ID、名称、类型、状态等，并能检索工单层级结构。
    • 时间表 (Timesheets): 检索时间表数据，支持按修改日期过滤，并能获取当前正在进行的时间表。
    • 用户 (Users): 获取用户信息，支持按修改日期过滤，并能获取当前用户和用户组信息。
    • 项目 (Projects): 检索项目和项目活动数据。
    • 报表 (Reports): 生成各类报表，包括当前总计快照、Payroll报表（可按工单分组）、项目报表等。
    • 自定义字段 (Custom Fields): 获取时间卡上配置的自定义跟踪字段。
    • 其他功能: 获取最后修改时间戳、通知、管理客户等。
  • MCP 协议支持: 完全遵循 MCP 协议规范，通过 JSON-RPC 协议与客户端通信，支持标准的初始化、工具列表、工具调用等 MCP 方法。
  • Stdio 传输: 使用标准输入/输出 (stdio) 作为默认的通信协议，易于集成和部署。
  • 可扩展性: 项目结构清晰，易于扩展和添加新的 QuickBooks Time API 工具。

安装步骤

  1. 安装 Python 依赖: 确保你的系统已安装 Python 和 pip。在终端中，导航到仓库根目录 'aallsbury_qb-time-mcp-server'，然后运行以下命令安装项目依赖： 
    pip install -r requirements.txt
  2. 配置 QuickBooks Time 访问令牌: 在仓库根目录下创建 '.env' 文件，并添加你的 QuickBooks Time API 访问令牌。请替换 'your_access_token_here' 为你的实际令牌。 
    QB_TIME_ACCESS_TOKEN=your_access_token_here
NODE_ENV=development  # 可选，设置运行环境为开发模式

服务器配置

要将此 MCP 服务器与 MCP 客户端（例如 Claude Desktop）连接，你需要在客户端中配置服务器信息。以下是一个 Claude Desktop 的配置示例，你需要将 '"your_quickbooks_time_access_token_here"' 替换为你的 QuickBooks Time API 访问令牌。

{
  "mcpServers": {
    "qb-time-tools": {  // 服务器名称，可以自定义
      "command": "python", // 启动服务器的命令
      "args": [          // 命令参数
        "./main.py"      // 服务器主脚本的路径
      ],
      "env": {           // 环境变量
        "QB_TIME_ACCESS_TOKEN": "your_quickbooks_time_access_token_here" // QuickBooks Time API 访问令牌
      }
    }
  }
}

配置说明:

  • '"qb-time-tools"': 服务器名称，你可以自定义，用于在 MCP 客户端中标识该服务器。
  • '"command": "python"': 指定用于启动服务器的命令为 'python'，假设你的 Python 环境已配置到系统路径。
  • '"args": ["./main.py"]': 指定传递给 'python' 命令的参数，'"./main.py"' 指示服务器的主程序入口点。
  • '"env": { "QB_TIME_ACCESS_TOKEN": ... }': 设置环境变量，'QB_TIME_ACCESS_TOKEN' 用于服务器验证 QuickBooks Time API 访问权限。

基本使用方法

  1. 启动 MCP 服务器: 在终端中，导航到仓库根目录 'aallsbury_qb-time-mcp-server'，运行以下命令启动服务器：

    python main.py

    服务器启动后，将监听标准输入/输出流上的 JSON-RPC 请求。

  2. 配置和连接 MCP 客户端: 在你的 MCP 客户端（如 Claude Desktop）中，根据上述 “服务器配置” 示例添加并配置 'qb-time-tools' 服务器。确保配置中的访问令牌 'QB_TIME_ACCESS_TOKEN' 与你在 '.env' 文件中设置的令牌一致。

  3. 通过 LLM 调用工具: 当客户端成功连接到 'qb-time-mcp-server' 后，你可以指示 LLM 使用已声明的工具来访问 QuickBooks Time 数据。例如，你可以指示 LLM “使用 'get_jobcodes' 工具获取所有活跃的工单代码” 或 “使用 'get_payroll' 工具生成指定日期范围的 Payroll 报表”。工具的具体名称、描述和参数请参考仓库 README.md 文件中 "Available Tools" 部分。

信息

分类

商业系统

访问项目