TimePRO MCP Server

An MCP (Model Context Protocol) server that wraps the TimePRO API, enabling AI assistants to automatically create and manage timesheets on behalf of authenticated users.

Features

• List clients - Search for clients to use in timesheets
• List projects - Get projects for a specific client
• List categories - Get available timesheet categories (Development, Meeting, etc.)
• List locations - Get available work locations
• Get timesheet defaults - Get default values including last used client/project
• List timesheets - View timesheets for a date range
• Get timesheet - Get full details of a specific timesheet
• Create timesheet - Create a new timesheet entry
• Update timesheet - Modify an existing timesheet
• Delete timesheet - Remove a timesheet

Quick Start (npx - No Installation Required)

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "timepro": {
      "command": "npx",
      "args": ["-y", "github:calumjs/TimePRO.MCP"],
      "env": {
        "TIMEPRO_API_URL": "https://ssw.sswtimepro.com",
        "TIMEPRO_API_KEY": "your-api-key-here",
        "TIMEPRO_TENANT_ID": "ssw"
      }
    }
  }
}

The config file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Configuration

The server requires three environment variables:

Variable	Description	Example
TIMEPRO_API_URL	TimePRO base URL	https://ssw.sswtimepro.com
TIMEPRO_API_KEY	Your personal access token	abc123...
TIMEPRO_TENANT_ID	Your tenant ID	ssw

How to Get Your API Key

1. Log into TimePRO: Go to your TimePRO instance and sign in
2. Navigate to API Key page: Go to Admin > API Key
3. Generate or Copy Key: If you already have a key, it will be displayed. Click "Generate" to create a new key if needed.
4. Copy the key: Store it securely

How to Find Your Tenant ID

The tenant ID is visible in:

1. The URL when logged into TimePRO (e.g., https://ssw.sswtimepro.com/b/ssw/... - tenant is "ssw")
2. The x-timepro-tenant-id header in browser dev tools (Network tab)
3. Ask your TimePRO administrator

Alternative: Local Installation

If you prefer to install locally:

git clone https://github.com/calumjs/TimePRO.MCP.git
cd TimePRO.MCP
npm install
npm run build

Then use this config:

{
  "mcpServers": {
    "timepro": {
      "command": "node",
      "args": ["/path/to/TimePRO.MCP/dist/index.js"],
      "env": {
        "TIMEPRO_API_URL": "https://ssw.sswtimepro.com",
        "TIMEPRO_API_KEY": "your-api-key-here",
        "TIMEPRO_TENANT_ID": "ssw"
      }
    }
  }
}

Usage Examples

Once configured, you can ask Claude to manage your timesheets naturally:

• "What clients do I have access to?"
• "Show me my timesheets for this week"
• "Create a timesheet for SSW internal work today from 9am to 5pm"
• "Log 2 hours of development work on the SugarLearning project"
• "Delete my timesheet from yesterday"

Tools Reference

list_clients

Search for clients by name.

Parameters:

• search_text (optional): Filter clients by name

list_projects

Get projects for a client.

Parameters:

• client_id (required): Client ID (string, e.g., "SSW")

list_categories

Get available timesheet categories. No parameters.

list_locations

Get available work locations. No parameters.

get_timesheet_defaults

Get default values for creating a timesheet.

Parameters:

• date (required): Date in YYYY-MM-DD format

list_timesheets

List timesheets in a date range.

Parameters:

• start_date (required): Start date in YYYY-MM-DD format
• end_date (required): End date in YYYY-MM-DD format

get_timesheet

Get details of a specific timesheet.

Parameters:

• timesheet_id (required): Timesheet ID (number)

create_timesheet

Create a new timesheet entry.

Parameters:

• client_id (required): Client ID (string)
• project_id (required): Project ID (string)
• category_id (required): Category ID (string)
• date (required): Date in YYYY-MM-DD format
• start_time (required): Start time in HH:MM format
• end_time (required): End time in HH:MM format
• break_minutes (optional): Break time in minutes (default: 0)
• location_id (optional): Work location ID
• billable_id (optional): Billable category ID
• note (optional): Description of work

update_timesheet

Update an existing timesheet.

Parameters:

• timesheet_id (required): Timesheet ID (number)
• All other parameters from create_timesheet (optional)

delete_timesheet

Delete a timesheet.

Parameters:

• timesheet_id (required): Timesheet ID (number)

Troubleshooting

"Missing required environment variables"

Ensure all three environment variables are set in your Claude Desktop config.

"TimePRO API error (401)"

Your API key may be invalid or expired. Generate a new one from TimePRO Admin > API Key.

"TimePRO API error (403)"

Your user account may not have permission for the requested operation.

Connection issues

Verify the TIMEPRO_API_URL is correct and accessible from your network.

License

MIT