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_st

... View full README on GitHub