TimeCard MCP

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

🚀 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/).

🛠️ 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 4 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

• timecard_get_timesheet - Get timesheet data for a week

Timesheet Operations

• timecard_set_timesheet_entry - Set project and activity for an entry

• timecard_set_daily_hours - Set hours for a specific day

• timecard_set_daily_note - Set note for a specific day

• timecard_clear_daily_hours - Clear all hours for a specific day

Management

• timecard_save_timesheet - Save timesheet changes permanently

• timecard_validate_timesheet - Validate timesheet for errors

• timecard_get_summary - Get timesheet summary statistics

See FEATURES.md for detailed usage.

License

MIT