Timesheet MCP Server

Timesheet MCP Server

Control Timesheet with natural language from AI assistants such as ChatGPT, Claude, Claude Code, Cursor, and VS Code. Start and stop timers, log past work, pull statistics and exports, request time off, and manage projects and teams by chatting.

The server supports the current version of the Model Context Protocol (2026-07-28) and the earlier ones, so it works with new and older clients alike. The full guide is at docs.timesheet.io.

Two ways to connect

Both offer the same tools. You need a Timesheet Pro plan or above, which includes API access.

Get an API key

In the Timesheet web app, go to Integrations > API Keys, select New API Key, and copy the key. The same key works for the hosted server, the local server, and the Timesheet API.

Use the hosted server

ChatGPT: turn on developer mode, add a connection with the URL https://mcp.timesheet.io, and sign in with your Timesheet account when asked.

Claude Code with an API key:

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

Cursor (~/.cursor/mcp.json):

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

Use the local server

Claude Code:

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

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows), and other clients with the same format:

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

Restart the client after you change its configuration. The guide has the setup for VS Code and other clients.

Example prompts

• "Start the timer for the website project"
• "Pause my timer, I'm taking lunch", then "Stop the timer"
• "Log 2 hours on the API project for Monday"
• "What did I work on yesterday?"
• "How many billable hours did I track in September?"
• "Email the September timesheet for Acme as a PDF to billing@acme.com"
• "Book me off next Friday"
• "Who on my team is tracking right now?"

Tools

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

The guide lists every tool.

Interactive cards

In clients that support MCP Apps, such as ChatGPT and Claude, the timer, new and changed time entries, statistics, exports, and absence requests appear as interactive cards. They follow the client's light or dark theme and language. Other clients show the same information as text.

Development

npm install
npm run build       # server and widgets
npm test            # unit tests
npm run test:e2e    # both protocol versions over stdio and HTTP, against the build
npm run dev         # HTTP server on http://127.0.0.1:3000

The HTTP server uses TIMESHEET_API_TOKEN for requests that bring no credentials, so leave it unset whenever the server can be reached from outside your computer. See .env.example for the other settings.

Troubleshooting

• Nothing responds, or you get an authentication error: check that TIMESHEET_API_TOKEN is set without extra spaces or quotes, and that the key still exists in Integrations > API Keys.
• The command is not found: check that Node.js 20 or higher is installed with node --version.
• A tool reports that it needs a higher plan: the MCP server works with a Pro plan or above.

License

MIT, see LICENSE.md.

Support

Report problems and ideas at github.com/timesheetIO/timesheet-mcp/issues.