Skip to main content

MCP server

The Timesheet MCP server lets you control your time tracking with natural language from AI assistants and editors. Start and stop timers, log past work, pull reports and exports, request time off, and manage projects by chatting in ChatGPT, Claude, Claude Code, Cursor, VS Code, and other tools that support the Model Context Protocol.

Pro plan

The MCP server requires a Pro plan or above, which includes API access. See the Plans page for the full comparison.

Playing the video loads it from YouTube.

What is MCP​

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to outside tools. The Timesheet MCP server exposes your account to the assistant, so when you say "start the timer for my website project", the assistant calls Timesheet to start it and confirms the result.

The server supports the current version of the protocol (2026-07-28) and the earlier ones, so it works with new and older clients alike.

Two ways to connect​

Hosted serverLocal server
Addresshttps://mcp.timesheet.ioRuns on your computer with npx @timesheet/mcp
Sign-inYour Timesheet account (OAuth 2.1), or an API keyAn API key
Use it withClaude, ChatGPT, and clients that connect to a URL, such as Claude Code, Cursor, and VS CodeClaude Desktop, Claude Code, Cursor, VS Code, and other MCP clients
RequirementsNone beyond your Pro planNode.js 20 or higher

Both give the assistant the same tools. The same API key works for the hosted server, the local server, and the Timesheet API.

Connect ChatGPT​

ChatGPT connects to the hosted server, so you do not need an API key or Node.js.

  1. In ChatGPT, turn on Developer mode. It is in the ChatGPT settings, and OpenAI moves it from time to time. See OpenAI's guide for its current location.
  2. Add a new connection and enter https://mcp.timesheet.io as the server URL.
  3. When ChatGPT asks, sign in with your Timesheet account and allow access.
  4. Start a new chat and ask "What's my timer status?" to confirm the connection.

Whether you can turn on developer mode depends on your ChatGPT plan and workspace settings.

Connect Claude​

Claude signs in with your Timesheet account, so you do not need an API key or Node.js.

Claude on the web and in the desktop app​

  1. In Claude, open Customize > Connectors and select Add custom connector.
  2. Enter https://mcp.timesheet.io as the server URL and select Add.
  3. Select Connect, sign in with your Timesheet account, and select Allow access.
  4. Start a new chat and ask "What's my timer status?" to confirm the connection.

On a Team or Enterprise plan, an owner first adds the connector under Organization settings > Connectors. Members then connect with their own Timesheet account.

Claude Code​

  1. Add the server:

    claude mcp add --transport http --scope user timesheet https://mcp.timesheet.io

  2. In Claude Code, run /mcp, select timesheet, and sign in with your Timesheet account.

--scope user makes the server available in all your projects. To connect with an API key instead, see Use the hosted server with an API key.

Get an API key​

Claude and ChatGPT sign in with your Timesheet account. Other clients, and the local server, connect with an API key. One key works for the MCP server and the Timesheet API.

  1. Open the web app and go to Integrations > API Keys (see API keys).
  2. Select New API Key, give it a name, and choose when it expires.
  3. Copy the key and store it somewhere safe.
Keep your key safe

Your API key grants full access to your account. Never share it or commit it to version control. If it is ever exposed, delete it and create a new one.

Use the hosted server with an API key​

Clients that connect to a URL can use the hosted server with your API key, so you do not need Node.js. The client sends the key in the Authorization header.

Claude Code​

claude mcp add --transport http --scope user timesheet https://mcp.timesheet.io --header "Authorization: Bearer your-api-token-here"

Cursor​

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "timesheet": {
      "url": "https://mcp.timesheet.io",
      "headers": {
        "Authorization": "Bearer your-api-token-here"
      }
    }
  }
}

VS Code​

Add to your user mcp.json (MCP: Open User Configuration) or to .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "timesheet-api-token",
      "description": "Timesheet API key",
      "password": true
    }
  ],
  "servers": {
    "timesheet": {
      "type": "http",
      "url": "https://mcp.timesheet.io",
      "headers": {
        "Authorization": "Bearer ${input:timesheet-api-token}"
      }
    }
  }
}

Install the local server​

Add the Timesheet server to your client's MCP configuration, using the API key you just created. Restart the client after you change the configuration.

Claude Code​

Run this command in your terminal:

claude mcp add timesheet --scope user -e TIMESHEET_API_TOKEN=your-api-token-here -- npx -y @timesheet/mcp

--scope user makes the server available in all your projects. Run claude mcp list to check that it is connected.

Claude Desktop​

Edit the configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "timesheet": {
      "command": "npx",
      "args": ["-y", "@timesheet/mcp"],
      "env": {
        "TIMESHEET_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Restart Claude Desktop, then ask "What's my timer status?" to confirm the connection.

Cursor​

Add the server to ~/.cursor/mcp.json to use it in all projects, or to .cursor/mcp.json in a project to use it there only:

{
  "mcpServers": {
    "timesheet": {
      "command": "npx",
      "args": ["-y", "@timesheet/mcp"],
      "env": {
        "TIMESHEET_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

VS Code​

Run MCP: Open User Configuration from the Command Palette to use the server in all workspaces, or create .vscode/mcp.json in a project. Add:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "timesheet-api-token",
      "description": "Timesheet API key",
      "password": true
    }
  ],
  "servers": {
    "timesheet": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@timesheet/mcp"],
      "env": {
        "TIMESHEET_API_TOKEN": "${input:timesheet-api-token}"
      }
    }
  }
}

VS Code asks for your API key the first time the server starts and stores it securely, so the key is not saved in the file.

Other clients​

Most MCP clients need the same three values:

  • Command: npx
  • Arguments: -y @timesheet/mcp
  • Environment variable: TIMESHEET_API_TOKEN set to your API key

Global install (optional)​

For faster startup, install the package once and point the command at it:

npm install -g @timesheet/mcp
{
  "mcpServers": {
    "timesheet": {
      "command": "timesheet-mcp",
      "env": {
        "TIMESHEET_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Example prompts​

Once connected, talk to your assistant in plain language. The exact wording does not matter, the assistant interprets your intent.

  • Timer: "Start the timer for the website project", "Pause my timer, I'm taking lunch", "Stop the timer", "What's my timer status?"
  • Tasks: "Add a note: fixed the login bug", "Add a $45 expense for lunch with the client", "Mark the current task as billable".
  • Projects: "Show my active projects", "Create a project called Website Redesign", "Archive the old website project".
  • History: "What did I work on yesterday?", "Show this week's time entries", "Log 2 hours on the API project for Monday".
  • Reports: "How many billable hours did I track in September?", "Export last month as an Excel file", "Email the September timesheet for Acme as a PDF to billing@acme.com".
  • Time off and team: "Book me off next Friday", "Show my pending absence requests", "Who on my team is tracking right now?"

Interactive cards​

In clients that support MCP Apps, such as ChatGPT and Claude, some results appear as interactive cards instead of plain text:

  • Timer: the running timer with a live clock and buttons to pause, resume, or stop it.
  • Time entries: the entry you added or changed, with project, time range, and duration.
  • Statistics: your total and billable hours with a bar per project. Select Expand to see the charts.
  • Exports: a confirmation when a report was sent, or a Download button when an export is ready.
  • Absences: the request and its status. You can cancel a pending request directly in the card with Cancel request.

Clients without MCP Apps support, such as Claude Code, show the same information as text.

Available tools​

The server provides more than 100 tools. The assistant picks the right ones for your request, so you do not need to name them.

Timer​

ToolDescription
timer_startStart a timer for a project, with an optional backdated start time
timer_stopStop the running timer and complete the task
timer_pausePause the timer for a break
timer_resumeResume the timer after a break
timer_statusCheck the current timer state
timer_updateUpdate the running timer (description, location, billable status, tags)

Task enhancements​

ToolDescription
task_add_noteAdd a note to the running task
task_add_expenseRecord an expense on the running task
task_add_pauseAdd a manual break to the running task

Projects​

ToolDescription
project_listList projects, with optional filters (status, team, search)
project_createCreate a project
project_updateUpdate a project or archive it
project_deletePermanently delete a project
project_getGet details for a project

Tasks​

ToolDescription
task_listList time entries, with date and project filters
task_createCreate a manual time entry for past work
task_updateChange a task's details, times, or billing status
task_deleteDelete a time entry
task_getGet details for a task

Reports and exports​

ToolDescription
statistics_getTotals, project breakdowns, and daily hours for a date range of up to one year
export_generateExport time entries as Excel, CSV, or PDF and get a download link
export_sendGenerate an export and send it to an email address
export_report_types, export_fieldsList the available report types and columns
export_from_template, export_template_list, export_template_get, export_template_create, export_template_update, export_template_deleteSave export settings as templates and reuse them
report_task_pdf, report_expense_pdf, report_note_pdfPDF for a single task, expense, or note (the matching _get tools return the data)
report_document_get, report_document_pdf, report_document_xmlInvoice or document data, PDF, or e-invoice XML (ZUGFeRD, XRechnung, ebInterface)

Absences and contracts​

ToolDescription
absence_list, absence_getList absences, with filters for person, type, status, and dates
absence_create, absence_update, absence_cancel, absence_deleteRequest, change, cancel, or delete an absence
absence_approve, absence_rejectApprove or reject a pending absence
absence_type_list, absence_type_get, absence_type_create, absence_type_update, absence_type_deleteManage absence types, such as vacation or sick leave
contract_list, contract_get, contract_create, contract_update, contract_deleteManage employment contracts
contract_activate, contract_suspend, contract_reactivate, contract_terminateChange a contract's status

Todos, notes, expenses, and breaks​

ToolDescription
todo_list, todo_get, todo_create, todo_update, todo_close, todo_reopen, todo_deleteManage todos, and close or reopen them
note_list, note_get, note_create, note_update, note_delete, note_file_urlManage notes and download their attachments
expense_list, expense_get, expense_create, expense_update, expense_delete, expense_refund, expense_file_urlManage expenses, mark them as refunded, and download receipts
pause_list, pause_get, pause_create, pause_update, pause_deleteManage breaks on tasks

Teams and organizations​

ToolDescription
team_listList teams
team_member_list, team_member_get, team_member_add, team_member_update, team_member_removeManage team members and invitations
team_member_statusSee which team members are tracking time right now
project_member_list, project_member_get, project_member_add, project_member_update, project_member_removeManage project members
organization_list, organization_get, organization_create, organization_update, organization_deleteManage organizations
organization_member_list, organization_member_get, organization_member_add, organization_member_update, organization_member_removeManage organization members and invitations

Tags, rates, and your account​

ToolDescription
tag_list, tag_get, tag_create, tag_update, tag_deleteManage tags
rate_list, rate_get, rate_create, rate_update, rate_deleteManage rates
profile_get, profile_updateView and update your profile
settings_get, settings_updateView and update your settings
auth_configureConfigure API authentication instead of the environment variable (local server only)

Troubleshooting​

Nothing responds, or you get an authentication error. Check that TIMESHEET_API_TOKEN is set correctly, with no extra spaces or quotes, and that the key still exists in Integrations > API Keys. Create a new key if needed, then restart the client.

The command is not found. Confirm Node.js 20 or higher is installed (node --version). If npx cannot find the package, install it globally with npm install -g @timesheet/mcp and use timesheet-mcp as the command.

ChatGPT cannot add the connection. Check that developer mode is on and that the URL is exactly https://mcp.timesheet.io. Your Timesheet account needs a Pro plan for the tools to work.

A timer will not start. Make sure the project name matches an existing project, and that you have access to it. Ask "What's my timer status?" to test the connection on its own.

Security​

The local server runs on your computer with your personal API key and talks directly to the Timesheet API, so the app does not need to be open. The hosted server does the same with your API key or your Timesheet sign-in.

In both cases the assistant acts with your account's permissions: it sees and changes only what you can see and change in the web app. It cannot change your subscription or billing. Many clients ask you to confirm each tool call, so check what the assistant is about to do, especially before it deletes something.

To revoke an API key, delete it in Integrations > API Keys. This disconnects every client and integration that uses the key, local or hosted. Then remove the server from your client's configuration. To disconnect ChatGPT, remove the connection in your ChatGPT settings.

See also​

Last updated on