TimeCard MCP

A Model Context Protocol (MCP) server for automating TimeCard timesheet management using Playwright browser automation.

⚡ Performance Optimizations

This MCP uses batch operations exclusively for optimal performance:

• 🚀 Batch Operations: Queue multiple updates and submit in a single request

  • 75% faster than legacy UI-based operations

  • Zero UI operations - direct form POST to server

• 💾 Session Persistence: Browser context reuse between restarts

  • 60% reduction in re-login frequency

  • Session state saved and restored automatically

Workflow:

• Use timecard_set_entries + timecard_set_hours + timecard_set_notes + timecard_save

🚀 Quick Start

Recommended: Use npx to run the TimeCard MCP server. This approach automatically fetches the latest version without manual maintenance (requires Node.js v18+).

Claude Desktop Integration

You can use the npx method directly in Claude Desktop configuration:

Benefits:

• Automatically stays up-to-date

• No manual installation or build required

• Simple configuration

• npx caches downloaded packages - won't re-download every time

Note: Ensure your TIMECARD_BASE_URL includes the application path (e.g., http://your-timecard-server/app/).

🤖 Quick Start for AI Agents

If you're an AI agent using TimeCard MCP to fill timesheets, follow this proven workflow for best results.

Core Principles

1. Entry Immutability

• Once an entry is configured with a project/activity, NEVER change it

• Changing project/activity clears ALL hours for that entry

• Use different entry indices (0-9) for different project/activity combinations

2. Workflow Order

• Configure ALL entries first

• Then fill ALL hours

• Then add ALL notes

• Finally save once

3. Data Visibility

• set_* functions queue updates in memory (temporary)

• save writes to server (permanent)

• get_timesheet reads from server (only shows saved data)

• Always call save before verifying with get_timesheet

Standard Workflow

Incremental Filling (Adding More Days)

If the week already has Mon-Wed filled and you need to add Thu-Fri:

Common Mistakes to Avoid

❌ DON'T check get_timesheet before save

❌ DON'T change project/activity of existing entry

Expected Success Rate

Following this workflow:

• ✅ First-time success rate: 90%+

• ✅ Tool calls needed: 5-6 for a full week

• ✅ Single POST request for all changes

🛠️ Advanced Setup: Local Development

For developers or users requiring specific version control, offline usage, or code modifications, you can opt for local installation:

1. Local Setup

2. Environment Configuration

The server requires the following environment variables to connect to your TimeCard system. You can create a .env file in the project root or set them in your shell:

3. Add to Claude Desktop (Local Version)

Edit your ~/Library/Application Support/Claude/claude_desktop_config.json file:

Note: Replace /absolute/path/to/timecard-mcp/ with the actual path where you cloned this repository.

When to use local installation:

• Code modification or extension required

• Specific version control needs

• Fully offline environment

• Development and debugging requirements

4. Restart Claude Desktop

After configuration, restart Claude Desktop. You should now see TimeCard tools available!

📚 Documentation

• FEATURES.md - Detailed documentation of all available MCP tools, parameters, return values, and usage examples

• DEVELOPMENT.md - Developer guide for understanding, modifying, or extending TimeCard MCP

🔧 Available Tools

The TimeCard MCP server provides 13 tools organized into 5 categories:

Authentication

• timecard_login - Login to TimeCard system

• timecard_logout - Logout from TimeCard system

• timecard_check_session - Check current session status

Data Retrieval

• timecard_get_projects - Get available projects

• timecard_get_activities - Get activities for a project (returns value field for use with set_entries)

• timecard_get_timesheet - Get timesheet data for a week (includes hours, status, notes per day)

  • Returns daily_status: draft | submitted | approved | rejected

  • Returns daily_notes: Notes for each day

• timecard_get_summary - Get timesheet summary statistics

Timesheet Operations

• timecard_set_entries - Queue project/activity configurations

• timecard_set_hours - Queue hour updates

• timecard_set_notes - Queue note updates

• timecard_save - Submit all queued updates in single POST

• timecard_discard - Discard queued updates

Utility

• timecard_version - Get MCP version info

  • Returns commit: Git hash (e.g., 801fd99 or 801fd99-dirty for uncommitted changes)

  • Returns branch: Git branch name

  • Returns buildDate: Build timestamp

See FEATURES.md for detailed usage.

License

MIT