TimeCard MCP Server

TimeCard MCP

透過 HTTP 直接操作 TimeCard 工時系統的 Model Context Protocol (MCP) 伺服器。

功能特色

• 無狀態工具：每次工具呼叫完全獨立，不依賴跨呼叫的共享狀態
• 原子性儲存：單一 timecard_save 即可同時處理項目、工時與備註
• 自動驗證：首次請求時自動登入，無需手動處理
• Session 持久化：HTTP session cookie 可跨重啟重複使用

快速開始

建議方式： 使用 npx 自動取得最新版本（需 Node.js v18+）。

export TIMECARD_USERNAME="你的帳號"
export TIMECARD_PASSWORD="你的密碼"
export TIMECARD_BASE_URL="http://your-timecard-server/app/"

npx git+https://github.com/keith-hung/timecard-mcp.git

Claude Desktop / Claude Code 整合

{
  "mcpServers": {
    "timecard": {
      "command": "npx",
      "args": ["git+https://github.com/keith-hung/timecard-mcp.git"],
      "env": {
        "TIMECARD_USERNAME": "你的帳號",
        "TIMECARD_PASSWORD": "你的密碼",
        "TIMECARD_BASE_URL": "http://your-timecard-server/app/"
      }
    }
  }
}

注意： TIMECARD_BASE_URL 必須包含完整的應用程式路徑（例如 http://your-server/app/）。

可用工具（6 個）

資料查詢

寫入

工具資訊

使用流程

1. get_timesheet("2026-03-02")          — 查看目前儲存的資料
2. get_activities("17647")              — 取得 activity_value
3. save({
     date: "2026-03-02",
     entries: [
       { entry_index: 0, project_id: "17647", activity_value: "true$9$17647$100" }
     ],
     hours: [
       { entry_index: 0, date: "2026-03-02", hours: 8.0 },
       { entry_index: 0, date: "2026-03-03", hours: 8.0 }
     ],
     notes: [
       { entry_index: 0, date: "2026-03-02", note: "Development" }
     ]
   })                                   — 原子性儲存
4. get_timesheet("2026-03-02")          — 驗證結果（選用）

重點說明

• 日期格式統一使用 YYYY-MM-DD — hours 和 notes 的日期必須與頂層 date 同一週
• entries 為選填 — 若該列已有正確的 project/activity，可省略
• 項目不可變性 — 變更既有項目的 project/activity 會清除其工時，請改用不同的 entry_index
• 備註限制 — 不可包含：#$%^&*=+{}[]|?'"

增量更新

若週一至週三已有工時，僅需補填週四、週五：

save({
  date: "2026-03-02",
  hours: [
    { entry_index: 0, date: "2026-03-05", hours: 8.0 },
    { entry_index: 0, date: "2026-03-06", hours: 8.0 }
  ]
})

無需重新指定 entries 或既有工時。save 工具會自動從伺服器重建完整表單，僅覆蓋你指定的變更。

本地開發

git clone https://github.com/keith-hung/timecard-mcp.git
cd timecard-mcp
npm install
npm run build

指向本地 build：

{
  "mcpServers": {
    "timecard": {
      "command": "node",
      "args": ["/path/to/timecard-mcp/dist/index.js"],
      "env": {
        "TIMECARD_USERNAME": "你的帳號",
        "TIMECARD_PASSWORD": "你的密碼",
        "TIMECARD_BASE_URL": "http://your-timecard-server/app/"
      }
    }
  }
}

授權

MIT