Paymo

This MCP server lets Claude Desktop manage Paymo time tracking and invoicing through natural language, turning your requests into Paymo API calls. It enables you to list projects and tasks, create time entries, batch-upload timesheets, and export invoice-related data, all while keeping your work organized and properly billed.

How to use

You interact with the Paymo MCP Server through an MCP client like Claude Desktop. The server translates your natural language requests into Paymo actions such as listing projects, listing tasks for a project, creating time entries, and exporting invoice timesheets. Use it to quickly log time, explore your Paymo data, and generate billable exports.

Key capabilities you can rely on include time entry management, project and task discovery, unbilled time analysis, batch entries from YAML, smart filtering, and chronological sorting of exports. For example you can ask to log hours against a specific project, fetch tasks for a project, or export the timesheet for a given invoice. The MCP server ensures only entries billed to a particular invoice are included in invoice exports and that all exports are sorted by date.

How to install

Prerequisites you need before you install: Python 3.8 or newer, a Paymo account with API access, and the MCP runtime dependency.

1. Install the MCP runtime tool if you don’t have it yet

2. Clone the Paymo MCP server repository (placeholder path shown in examples) and install Python dependencies

3. Run the MCP server with Python to start listening for MCP clients

Configuration overview

The server relies on two configuration files for non-sensitive settings and authentication.

Non-sensitive settings are stored at the following path: ~/.mcp-config/paymo/config.json. This file holds your timezone and a mapping of Paymo projects to Paymo IDs and their relevant task IDs. Example:{

{ "timezone": "America/Chicago", "projects": { "Client Matter Name": { "project_id": 12345, "task_id": 67890 } } }

Authentication and API keys

Sensitive credentials live in ~/.mcp-auth/paymo/auth.json. This file stores your Paymo API key. Example structure shown here is a placeholder for your actual key.

Starting the MCP server and configuring Claude Desktop

To start the MCP server locally, run the Python script that implements the MCP endpoint.

Configure Claude Desktop to connect to the local MCP server by adding a configuration entry with the Python command and the path to the script, followed by the mcp task name as an argument. The example below demonstrates the expected shape for the connection entry.

Example CLI start command you will run to start the server

MCP server commands and usage notes

The server exposes a set of functions to support Paymo data operations. These include listing Paymo projects, listing tasks for a project, creating a time entry, submitting multiple entries from YAML, listing entries with filters, and exporting invoice-specific timesheets.

All timesheet exports are chronologically sorted by date and include task names, descriptions, and hours. Invoice exports filter to include only entries billed on the specified invoice and look back up to 90 days to capture relevant entries.

Troubleshooting

If you encounter issues connecting to or running the MCP server, verify that the API key is configured in the authentication file and that the non-sensitive config maps your Paymo projects to IDs correctly. Ensure the MCP runtime tool is installed and that the start command matches the expected script path.

Available tools

list_paymo_projects

List all active Paymo projects and return their IDs, names, and client details.

list_paymo_tasks

List all tasks for a given Paymo project by project_id and return task IDs, names, and billing info.

create_paymo_entry

Create a single time entry with a task_id, date, duration_hours, and description.

submit_paymo_timesheet

Submit multiple time entries from a YAML string and receive a summary of the created entries.

list_paymo_entries

List time entries within a date range with optional filters for project_id and billed status.

list_paymo_invoices

List Paymo invoices with optional filters for client and status.

get_outstanding_invoices_last_week

Retrieve outstanding invoices from the last seven days.

export_invoice_timesheet

Export a detailed CSV timesheet for a specific invoice, including only billed entries and sorted by date.

export_paymo_timesheet

Export a timesheet for a given date range with optional project filtering and format selection.