Skip to main content
Glama
Sign In
TimeCard MCP

TimeCard MCP

by keith-hung
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

TimeCard MCP

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

功能特色

  • 無狀態工具：每次工具呼叫完全獨立，不依賴跨呼叫的共享狀態

  • 原子性儲存：單一 timecard_save 即可同時處理項目、工時與備註

  • 自動驗證：首次請求時自動登入，無需手動處理

  • Session 持久化：HTTP session cookie 可跨重啟重複使用

Related MCP server: MCP Playwright Server

快速開始

建議方式： 使用 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/"
      }
    }
  }
}

授權

MIT

Available Tools

6 tools
timecard_get_activitiesB

Get list of activities for a specific project. Returns activity id, name, and value.

The 'value' field (format: "bottom$uid$pid$progress") is the activity_value needed by timecard_save's entries parameter.

Inputs: project_id (required).

timecard_get_projectsA

Get list of available projects. Returns project id and name.

Use the project id with timecard_get_activities to get activity options, and with timecard_save to set entries.

Inputs: no named parameters.

timecard_get_summaryC

Get summary statistics for the current timesheet week

Inputs: date (required).

timecard_get_timesheetA

Get timesheet data for a specific week. Read-only, no side effects.

Returns for each entry:

  • daily_hours: Hours worked each day (monday-saturday)

  • daily_status: Approval status each day (draft/submitted/approved/rejected)

  • daily_notes: Notes for each day

Status values:

  • draft: Saved but not submitted

  • submitted: Submitted for approval

  • approved: Approved by manager

  • rejected: Rejected by manager

This retrieves SAVED data from the server. Use timecard_save to make changes.

Inputs: date (required).

timecard_saveA

Atomic save: apply entries, hours, and notes to a specific week in one operation.

This tool fetches the target week's page, reconstructs the full form state, applies your changes on top, and POSTs to the server — all in a single call. No prior setup needed other than authentication (handled automatically).

Parameters:

  • date (REQUIRED): YYYY-MM-DD — any date in the target week. Determines which week to save to.

  • entries: Set project/activity for row slots. Get activity_value from timecard_get_activities.

  • hours: Set hours for specific days. Use date in YYYY-MM-DD format.

  • notes: Set notes for specific days. Use date in YYYY-MM-DD format.

All dates in hours/notes must fall within the same week as the top-level date.

⚠️ WORKFLOW:

  1. timecard_get_timesheet(date) — view current data

  2. timecard_get_activities(project_id) — get activity_value for entries

  3. timecard_save({ — atomic 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" } ] })

NOTE: Only 'save' (draft) is supported. 'submit' (for approval) is strictly prohibited. WARNING: Notes cannot contain special characters: #$%^&*=+{}[]|?'"

Inputs: date (required), entries, hours, notes.

timecard_versionA

Get TimeCard MCP version information.

Returns:

  • commit: Git commit hash (e.g., "801fd99" or "801fd99-dirty" if has uncommitted changes)

  • branch: Git branch name (e.g., "v2-batch-operations")

  • buildDate: ISO timestamp when the MCP was built

Use this to verify which version of TimeCard MCP is running.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct purpose with no overlap: timecard_get_activities retrieves activities for a project, timecard_get_projects lists projects, timecard_get_summary provides weekly statistics, timecard_get_timesheet fetches weekly data, timecard_save performs atomic updates, and timecard_version returns version info. The descriptions clearly differentiate their functions, preventing agent misselection.

    Naming Consistency5/5

    All tools follow a consistent snake_case naming pattern with a 'timecard_' prefix and descriptive verb_noun combinations (e.g., timecard_get_activities, timecard_save). This uniformity makes the tool set predictable and easy to understand for agents.

    Tool Count5/5

    With 6 tools, the server is well-scoped for managing timesheets, covering key operations like viewing projects, activities, timesheet data, summaries, saving entries, and checking version. Each tool serves a necessary function without redundancy, fitting typical MCP server ranges.

    Completeness4/5

    The tool set covers core timesheet workflows: retrieving data (projects, activities, timesheets, summaries) and saving changes. A minor gap exists as the server lacks a tool for submitting timesheets for approval (only draft saves are supported), which might limit full lifecycle coverage but is workable for basic operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • MCP Playwright Server

      MostafaRaafat91
      A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI-powered browser automation, web scraping, and testing using Playwright across Chromium, Firefox, and WebKit. It allows users to perform actions like navigation, clicking, typing, and taking screenshots through natural language interfaces.
      24 npm
      MIT

    • Playwrightium

      analysta-ai
      A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for browser automation that allows AI to perform web tasks using Playwright through direct commands, reusable YAML shortcuts, or custom scripts. It features secure environment variable management and guided automation creation to build robust, repeatable browser workflows.
      34 npm
      MIT

    • TimePRO MCP Server

      calumjs
      A
      license
      A
      quality
      D
      maintenance
      An MCP server that wraps the TimePRO API, enabling AI assistants to automatically create, view, and manage timesheets for authenticated users. It provides tools for searching clients and projects, retrieving configuration defaults, and performing full CRUD operations on timesheet entries.
      10
      MIT