# Timesheet Mcp

> Official Model Context Protocol (MCP) server for Timesheet API. Control your timer with natural language in Claude, Cursor, and other MCP-compatible clients. Track time, manage projects, and log expenses seamlessly.

- **Type:** MCP server
- **Install:** `agentstack add mcp-timesheetio-timesheet-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [timesheetIO](https://agentstack.voostack.com/s/timesheetio)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [timesheetIO](https://github.com/timesheetIO)
- **Source:** https://github.com/timesheetIO/timesheet-mcp
- **Website:** https://timesheet.io

## Install

```sh
agentstack add mcp-timesheetio-timesheet-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Timesheet MCP Server

[](https://www.npmjs.com/package/@timesheet/mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)

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):

```bash
npx @timesheet/mcp
```

### Global Installation

For frequent use, you can install globally:

```bash
npm install -g @timesheet/mcp
timesheet-mcp
```

### Local Installation

For project-specific installation:

```bash
npm install @timesheet/mcp
```

## Configuration

### Using Environment Variables

Create a `.env` file with your API token:

```env
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`

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

For a globally installed version:

```json
{
  "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

```bash
# 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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [timesheetIO](https://github.com/timesheetIO)
- **Source:** [timesheetIO/timesheet-mcp](https://github.com/timesheetIO/timesheet-mcp)
- **License:** MIT
- **Homepage:** https://timesheet.io

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-timesheetio-timesheet-mcp
- Seller: https://agentstack.voostack.com/s/timesheetio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.