MCP server

The Timesheet MCP server lets you control your time tracking with natural language from AI assistants and editors. Start and stop timers, manage projects, add notes, and log expenses by chatting in Claude Desktop, 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.

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.

Before you start

A Timesheet Pro plan.
A Timesheet API key (see below).
A client that supports MCP, such as Claude Desktop, Claude Code, Cursor, or VS Code.
Node.js 18 or higher, so the server can run through npx.

Get an API key

Open the web app and go to Integrations > API Keys (see API keys).
Select New API Key, give it a name, and choose when it expires.
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.

Install

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

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": ["@timesheet/mcp"],
      "env": {
        "TIMESHEET_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

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

Claude Code

Add the server to ~/.claude/settings.json:

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

The Timesheet tools are then available in your Claude Code sessions.

Cursor

Go to Cursor Settings > Features > MCP Servers and add:

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

VS Code with Continue

Install the Continue extension, then add the server to its configuration:

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

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

Available tools

The server provides these tools to the assistant:

Timer

Tool	Description
`timer_start`	Start a timer for a project, with an optional backdated start time
`timer_stop`	Stop the running timer and complete the task
`timer_pause`	Pause the timer for a break
`timer_resume`	Resume the timer after a break
`timer_status`	Check the current timer state
`timer_update`	Update the running timer (description, location, billable status, tags)

Task enhancements

Tool	Description
`task_add_note`	Add a note to the running task
`task_add_expense`	Record an expense on the running task
`task_add_pause`	Add a manual break to the running task

Projects

Tool	Description
`project_list`	List projects, with optional filters (status, team, search)
`project_create`	Create a project
`project_update`	Update a project or archive it
`project_delete`	Permanently delete a project
`project_get`	Get details for a project

Tasks

Tool	Description
`task_list`	List time entries, with date and project filters
`task_create`	Create a manual time entry for past work
`task_update`	Change a task's details, times, or billing status
`task_delete`	Delete a time entry
`task_get`	Get details for a task

Teams and authentication

Tool	Description
`team_list`	List teams, for filtering projects
`auth_configure`	Configure API authentication instead of the environment variable

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

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 server runs locally with your personal API key and talks directly to the Timesheet API, so the app does not need to be open. It can read and create time entries, manage your projects, and add notes, expenses, and breaks. It cannot reach other users' private data or change your billing.

To revoke access, delete the API key in Integrations > API Keys and remove the server from your client's configuration.

What is MCP​

Before you start​

Get an API key​

Install​

Claude Desktop​

Claude Code​

Cursor​

VS Code with Continue​

Global install (optional)​

Example prompts​

Available tools​

Timer​

Task enhancements​

Projects​

Tasks​

Teams and authentication​

Troubleshooting​

Security​

See also​