TimeCard

TimeCard MCP is a server that automates TimeCard timesheet management through a Model Context Protocol interface, using Playwright browser automation to perform actions like logging in, retrieving data, and updating timesheets. It enables your MCP-enabled clients to run TimeCard-related tasks programmatically and in automation workflows.

How to use

You interact with TimeCard MCP through an MCP client. The server exposes a set of tools that let you authenticate, fetch data (projects, activities, and timesheets), modify timesheet entries, and manage the lifecycle of a timesheet. Use an MCP client to call the available tools in sequence to automate common tasks such as creating or updating a week’s timesheet, validating entries, and saving changes.

How to install

Prerequisites: you need Node.js v18 or newer installed on your system.

Option A — Quick Start with npx (recommended)

Set your TimeCard credentials and base URL in your environment:

export TIMECARD_USERNAME="your_username"

export TIMECARD_PASSWORD="your_password"

export TIMECARD_BASE_URL="http://your-timecard-server/app/"

Run the server using npx with the GitHub MCP package URL:

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

Option B — Local development (advanced users)

Clone the repository, install dependencies, and build the project, then start it locally:

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

cd timecard-mcp

npm install

npm run build

Environment variables you set for local runs are the same as above.

To run in Claude Desktop, you can configure a local version that points to a built index file, as shown in the local configuration example.

Configuration and runtime details

When using Claude Desktop, you can point the MCP client to a local or remote instance. The TimeCard MCP server expects the following environment variables to be available to the process at runtime:

Notes and tips

Ensure the TIMECARD_BASE_URL includes the application path (for example, http://your-timecard-server/app/). This helps the server locate the TimeCard application correctly.

npx caches downloaded packages, so subsequent uses are faster and do not re-download every time.

Security considerations

Treat TIMECARD_USERNAME, TIMECARD_PASSWORD, and TIMECARD_BASE_URL as sensitive credentials. Store them securely and avoid sharing them in logs or screenshots. Use separate credentials for automation and monitor their usage to prevent misuse.

Available tools

timecard_login

Login to TimeCard system and establish a session for subsequent operations.

timecard_logout

Logout from TimeCard and terminate the session.

timecard_check_session

Verify whether a valid session is active.

timecard_get_projects

Retrieve the list of available projects.

timecard_get_activities

Retrieve activities for a selected project.

timecard_get_timesheet

Fetch timesheet data for a given week.

timecard_set_timesheet_entry

Set project and activity for a specific timesheet entry.

timecard_set_daily_hours

Set hours for a specific day in the timesheet.

timecard_set_daily_note

Attach a note to a specific day in the timesheet.

timecard_clear_daily_hours

Clear all hours for a specific day.

timecard_save_timesheet

Save the current timesheet changes permanently.

timecard_validate_timesheet

Validate the timesheet for errors before saving.

timecard_get_summary

Get summary statistics for the current timesheet period.