# 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.

[![Demo video](https://img.youtube.com/vi/NRekKgVbQno/hqdefault.jpg)](https://youtu.be/NRekKgVbQno)

Watch the video above for more information.

## 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`):

```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:

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

Then use this config:

```json
{
  "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