projectx-mcp

通过与 Claude Desktop 对话，在 ProjectX 中记录工时。

“记录今天 Ontrac 的 8 小时工时” “用 Ontrac 填补本周缺失的日期” “我这个月有哪些日期漏记了工时？”

安装

macOS (自动化)

git clone git@github.com:agustindiezdb/projectx-mcp.git
cd projectx-mcp
bash scripts/install.sh

该脚本将：

• 安装依赖项

• 构建项目

• 自动配置 Claude Desktop

• 创建现有配置的备份

然后重启 Claude Desktop。Chrome 将自动打开以使用您的 Dualboot Google 账户登录。

就是这样！ 您现在可以要求 Claude 记录您的工时了。

Windows

git clone git@github.com:agustindiezdb/projectx-mcp.git
cd projectx-mcp
npm install
npm run build

然后手动编辑 Claude Desktop 配置：

打开：%APPDATA%\Claude\claude_desktop_config.json

添加：

{
  "mcpServers": {
    "projectx": {
      "command": "node",
      "args": ["C:\\full\\path\\to\\projectx-mcp\\dist\\src\\server.js"]
    }
  }
}

将 C:\full\path\to\ 替换为您的实际路径（Windows 路径请使用 \）。

然后重启 Claude Desktop。Chrome 将自动打开以进行登录。

手动安装

如果您更喜欢手动配置：

1. 克隆并构建：

   git clone git@github.com:agustindiezdb/projectx-mcp.git
   cd projectx-mcp
   npm install
   npm run build

2. 编辑 Claude Desktop 配置：
   打开 ~/Library/Application Support/Claude/claude_desktop_config.json 并添加：

   {
     "mcpServers": {
       "projectx": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/projectx-mcp/dist/src/server.js"]
       }
     }
   }

   将 /ABSOLUTE/PATH/TO/ 替换为您克隆仓库的完整路径。

3. 重启 Claude Desktop

与 Cursor 一起使用

Cursor 使用每个项目独立的 MCP 配置。在您的项目根目录中创建 .cursor/mcp.json：

{
  "$schema": "https://json.schemastore.org/mcp.json",
  "mcpServers": {
    "projectx": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/projectx-mcp/dist/src/server.js"]
    }
  }
}

将 /ABSOLUTE/PATH/TO/ 替换为您克隆仓库的完整路径。

然后重启 Cursor。首次运行时，Chrome 将打开以进行登录。

使用方法

只需自然地与 Claude 对话：

Log 8 hours of Ontrac for today with description "Sprint planning"

Check my entries for this week and fill the missing days with 8h of Ontrac

Delete yesterday's entry and log 4h of Internal — Administrative

Which days am I missing hours for April?

可用工具

如果登录失败或会话过期

只需重启 Claude Desktop。Chrome 将再次打开供您登录。

有用的脚本

您也可以直接使用 API，无需通过 Claude Desktop：

# Test the API (creates and deletes a test entry)
npm run test:entry

# Check which days you're missing hours in April
npx ts-node scripts/check-april.ts

# Manually refresh your session (if expired)
npm run save-session

开发者指南

架构

Claude Desktop → MCP Server (stdio) → fetch() + _interslice_session cookie → ProjectX API

会话 cookie 存储在 ~/Library/Application Support/projectx-mcp/auth.json 中（已在 gitignore 中忽略）。

启动时，如果未找到有效会话，Chrome 会通过 Playwright 自动打开以进行登录。

开发模式

npm run dev

这会使用 ts-node 运行服务器，以便快速开发（无需构建步骤）。

工作原理

1. 身份验证：使用 Playwright 打开 Chrome，并通过轮询 /api/v1/current_user 自动检测登录是否成功

2. 会话持久化：使用 Playwright 的 storageState() 将 cookie 保存到 auth.json

3. API 客户端：读取 _interslice_session cookie 并向 ProjectX 发送经过身份验证的请求

4. MCP 协议：通过 stdio 传输向 Claude Desktop 公开 4 个工具

Claude Desktop 配置 (手动)

如果您更喜欢手动编辑：

{
  "mcpServers": {
    "projectx": {
      "command": "node",
      "args": ["/path/to/projectx-mcp/dist/src/server.js"]
    }
  }
}

故障排除

• 会话过期 → 重启 Claude Desktop，Chrome 会自动打开

• 找不到 Chrome → 安装 Google Chrome（必须在系统 PATH 中）

• 找不到项目 → 要求 Claude 运行 get_projects 以查看确切名称

• 路径问题 (macOS/Linux) → 使用绝对路径，不要使用 ~ 或相对路径

• 路径问题 (Windows) → 在 JSON 路径中使用 \（双反斜杠），例如 C:\Users\...

• 认证文件位置：

  • macOS: ~/Library/Application Support/projectx-mcp/auth.json

  • Windows: %APPDATA%\projectx-mcp\auth.json

  • Linux: ~/.config/projectx-mcp/auth.json

要求

• 操作系统： macOS, Windows 或 Linux

• Node.js： 20+

• 浏览器： Google Chrome（自动登录必需）

• Claude Desktop

• Dualboot Google 账户

许可证

Dualboot Partners 内部工具。