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+).

# 1. Set environment variables (replace with your actual credentials)
export TIMECARD_USERNAME="your_username"
export TIMECARD_PASSWORD="your_password"
export TIMECARD_BASE_URL="http://your-timecard-server/app/"

# 2. Run the server
npx git+https://github.com/keith-hung/timecard-mcp.git

Claude Desktop Integration

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

{
  "mcpServers": {
    "timecard": {
      "command": "npx",
      "args": ["git+https://github.com/keith-hung/timecard-mcp.git"],
      "env": {
        "TIMECARD_USERNAME": "your_username",
        "TIMECARD_PASSWORD": "your_password",
        "TIMECARD_BASE_URL": "http://your-timecard-server/app/"
      }
    }
  }
}

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

# 1. Clone the repository
git clone https://github.com/keith-hung/timecard-mcp.git
cd timecard-mcp

# 2. Install dependencies and build
npm install
npm run build

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:

export TIMECARD_USERNAME="your_username"
export TIMECARD_PASSWORD="your_password"
export TIMECARD_BASE_URL="http://your-timecard-server/app/"

3. Add to Claude Desktop (Local Version)

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

{
  "mcpServers": {
    "timecard": {
      "command": "node",
      "args": ["/absolute/path/to/timecard-mcp/dist/index.js"],
      "env": {
        "TIMECARD_USERNAME": "your_username",
        "TIMECARD_PASSWORD": "your_password",
        "TIMECARD_BASE_URL": "http://your-timecard-server/app/"
      }
    }
  }
}

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