timesheetIO/timesheet-mcp

Timesheet MCP Server

A Model Context Protocol (MCP) server that provides natural language access to the Timesheet API through standardized tools.

Features

• Timer Management: Start, stop, pause, and resume timers with natural language
• Task Enhancement: Add notes, expenses, and pauses to running tasks
• Project Management: Create, update, list, and delete projects
• Task Management: Full CRUD operations for tasks
• Natural Language Support: Use simple phrases to control your timer

Installation

Quick Start with npx

The easiest way to use the Timesheet MCP server is with npx (no installation required):

npx @timesheet/mcp

Global Installation

For frequent use, you can install globally:

npm install -g @timesheet/mcp
timesheet-mcp

Local Installation

For project-specific installation:

npm install @timesheet/mcp

Configuration

Using Environment Variables

Create a .env file with your API token:

TIMESHEET_API_TOKEN=your-api-token-here

Using Claude Desktop

Add to your Claude Desktop 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-server"],
      "env": {
        "TIMESHEET_API_TOKEN": "your-api-token"
      }
    }
  }
}

For a globally installed version:

{
  "mcpServers": {
    "timesheet": {
      "command": "timesheet-mcp",
      "env": {
        "TIMESHEET_API_TOKEN": "your-api-token"
      }
    }
  }
}

Sample Prompts

Timer Control

• Start timer:

  • "Start the timer for ProjectX"
  • "Start timer for ProjectX 10 minutes ago"
  • "Begin tracking time on the mobile app project"

• Stop timer:

  • "Stop the timer"
  • "Stop working"
  • "I'm done for the day"

• Pause timer:

  • "I have a break"
  • "Pause the timer"
  • "Taking lunch"

• Resume timer:

  • "Resume work"
  • "Back from break"
  • "Continue timer"

• Check status:

  • "What's my timer status?"
  • "Am I tracking time?"
  • "Show current timer"

Task Enhancements

• Add notes:

  • "Add a note: Fixed the login bug"
  • "Note that I spoke with the client about requirements"

• Add expenses:

  • "Add expense: $45 for lunch with client"
  • "Record taxi expense of $25"

• Update task:

  • "Update the description to 'Working on API integration'"
  • "Mark current task as billable"
  • "Add feeling rating of 4"

Project Management

• List projects:

  • "Show me all my projects"
  • "List active projects"
  • "What projects do I have?"

• Create project:

  • "Create a new project called 'Website Redesign'"
  • "Add project 'Mobile App v2' with default billable tasks"

• Update project:

  • "Archive the old website project"
  • "Rename project X to 'Client Portal'"

Task Management

• List tasks:

  • "Show today's tasks"
  • "List all running tasks"
  • "What did I work on yesterday?"

• Create task:

  • "Create a 2-hour task for ProjectX from 9am to 11am"
  • "Log 4 hours on the API project for yesterday"

• Update task:

  • "Mark task X as paid"
  • "Update task description"
  • "Change task to non-billable"

Available Tools

Timer Operations

• timer_start - Start timer for a project
• timer_stop - Stop the running timer
• timer_pause - Pause the timer (start break)
• timer_resume - Resume timer after break
• timer_status - Check current timer status
• timer_update - Update running timer details

Task Enhancements

• task_add_note - Add note to current task
• task_add_expense - Add expense to current task
• task_add_pause - Add manual pause to current task

Project Management

• project_list - List all projects
• project_create - Create new project
• project_update - Update existing project
• project_delete - Delete project

Task Management

• task_list - List tasks with filters
• task_create - Create new task
• task_update - Update existing task
• task_delete - Delete task

Authentication

• auth_configure - Set API authentication

Getting Your API Token

1. Log in to your Timesheet account
2. Go to Settings → API Access
3. Generate a new API token
4. Copy the token and add it to your configuration

Development

# Clone the repository
git clone https://github.com/timesheet/timesheet-mcp.git
cd timesheet-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

Troubleshooting

Timer not starting?

• Ensure you have a valid API token configured
• Check that the project ID exists in your account
• Verify you have permission to create tasks for the project

Authentication errors?

• Double-check your API token is correct
• Ensure the token hasn't expired
• Try generating a new token from your Timesheet settings

License

MIT

Support

For issues and feature requests, visit: https://github.com/timesheet/timesheet-mcp/issues