How do I use TimeCard MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TimeCard MCP Add 8 hours to Project Phoenix for today and save it" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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 個）

資料查詢

工具	說明
`timecard_get_projects`	取得可用專案（回傳 `id` 供其他工具使用）
`timecard_get_activities(project_id)`	取得專案下的活動（回傳 `value` 供 `save` 使用）
`timecard_get_timesheet(date)`	取得某週工時表資料（工時、狀態、備註）
`timecard_get_summary(date)`	取得每週摘要統計

寫入

工具	說明
`timecard_save(date, entries?, hours?, notes?)`	原子性儲存 — 一次 POST 套用所有變更

工具資訊

工具	說明
`timecard_version`	取得 MCP 版本資訊（commit、branch、build date）

使用流程

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/"
      }
    }
  }
}