playbooks

home / mcp / timepro mcp server

TimePRO MCP Server

Provides an MCP server to manage TimePRO timesheets through API.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "calumjs-timepro.mcp": {
      "command": "npx",
      "args": [
        "-y",
        "github:calumjs/TimePRO.MCP"
      ],
      "env": {
        "TIMEPRO_API_KEY": "YOUR_API_KEY",
        "TIMEPRO_API_URL": "https://ssw.sswtimepro.com",
        "TIMEPRO_TENANT_ID": "ssw"
      }
    }
  }
}

You can use the TimePRO MCP Server to securely create, view, and manage timesheets on behalf of authenticated TimePRO users. This MCP wraps the TimePRO API and exposes a set of endpoints that let you list clients, projects, categories, and locations, as well as create, read, update, and delete timesheets. It enables seamless automation through MCP clients, making timesheet workflows faster and more reliable.

How to use

You will connect an MCP client to the TimePRO MCP Server and provide the required API URL and credentials. Once connected, you can perform the following actions: list clients, list projects for a client, list categories, list locations, fetch timesheet defaults, list timesheets within a date range, get full details of a specific timesheet, and create, update, or delete timesheets. Use natural language prompts in your MCP client to perform these actions, such as requesting your timesheets for this week or creating a new timesheet for a specific project.

Two practical ways to run the MCP server are provided: a quick start using npx without installation and a local installation path if you prefer hosting the server yourself. Both configurations require three environment variables to be set: the TimePRO base URL, your API key, and your tenant ID.

How to install

Prerequisites: you should have Node.js and npm installed on your machine. You can verify by running the following commands.

node -v
npm -v

Option A: Quick Start using npx (no installation required) — configure your client with the following MCP server entry.

{
  "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"
      }
    }
  }
}

Option B: Local installation (clone and run locally). This is useful if you want to host the MCP server on your own infrastructure.

git clone https://github.com/calumjs/TimePRO.MCP.git
cd TimePRO.MCP
npm install
npm run build
```
Then configure the server to run from the built dist file.

Local installation configuration example (run from the built project):

{
  "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"
      }
    }
  }
}

Additional configuration and security notes

Environment variables required to run the server are listed below. Keep these values secure and do not expose them in client-side configurations.

TIMEPRO_API_URL is the TimePRO base URL you will connect to. TIMEPRO_API_KEY is your personal access token for API authentication. TIMEPRO_TENANT_ID identifies your TimePRO tenant.

Troubleshooting

If you see missing environment variables, ensure all three required variables are present in your MCP configuration. If you encounter a 401 error, your API key may be invalid or expired; generate a new key from TimePRO Admin > API Key. A 403 error typically indicates insufficient permissions for the requested operation. For connection issues, verify the TIMEPRO_API_URL is correct and accessible from your network.

Tools reference and capabilities

The TimePRO MCP Server exposes the following actions through its tools:

  • list_clients — Search for clients by name.
  • list_projects — Get projects for a client.
  • list_categories — Get available timesheet categories.
  • list_locations — Get available work locations.
  • get_timesheet_defaults — Get default values for creating a timesheet.
  • list_timesheets — List timesheets in a date range.
  • get_timesheet — Get details of a specific timesheet.
  • create_timesheet — Create a new timesheet entry.
  • update_timesheet — Update an existing timesheet.
  • delete_timesheet — Delete a timesheet.

Available tools

list_clients

Search for clients by name.

list_projects

Get projects for a client.

list_categories

Get available timesheet categories.

list_locations

Get available work locations.

get_timesheet_defaults

Get default values for creating a timesheet.

list_timesheets

List timesheets in a date range.

get_timesheet

Get details of a specific timesheet.

create_timesheet

Create a new timesheet entry.

update_timesheet

Update an existing timesheet.

delete_timesheet

Delete a timesheet.