MCP Server Integration

Control your time tracking with natural language through AI assistants. The Timesheet MCP Server lets you start timers, manage projects, add notes, and track expenses using simple conversational commands in Claude Desktop, ChatGPT, VS Code, and other MCP-compatible tools.

Pro Plan Required

MCP Server integration is available exclusively with Timesheet Pro subscription. See Plans & Pricing for details.

---

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect with external tools and services. Think of it as a universal adapter that lets AI assistants like Claude interact directly with Timesheet.

How It Works

1. You speak naturally - "Start the timer for my website project"
2. AI understands intent - Claude interprets your request
3. MCP executes action - The Timesheet MCP server starts your timer
4. AI confirms result - "Timer started for Website Redesign at 9:30 AM"

Real-World Example

Without MCP:

• Open Timesheet app
• Navigate to projects
• Find correct project
• Click start timer
• Add description manually

With MCP:

• Tell Claude: "Start timer for the API project and note that I'm working on authentication"
• Done. Timer running with description added.

---

Why Use the MCP Server?

Natural Language Control

• No app switching - Control Timesheet from your AI assistant
• Conversational commands - "I'm taking a lunch break" pauses your timer
• Context-aware - "Add a note about the client call" attaches to your current task
• Flexible phrasing - Say it however feels natural

Hands-Free Time Tracking

• Voice-friendly - Great with voice-to-text input
• Minimal friction - Track time without interrupting your workflow
• Quick updates - "Mark current task as billable" takes seconds
• Batch operations - "Show me what I worked on yesterday"

AI-Powered Assistance

• Smart suggestions - AI can help categorize work
• Time analysis - Ask about your time patterns
• Report summaries - "How many hours did I log this week?"
• Project overview - "What are my active projects?"

---

Getting Started

Prerequisites

Requirements:

• Timesheet Pro subscription
• Timesheet API token (from Settings → API Access)
• An MCP-compatible client (Claude Desktop, VS Code, etc.)
• Node.js 18 or higher (for npm installation)

Get Your API Token

1. Log in to Timesheet at my.timesheet.io
2. Go to Integrations → API Keys
3. Click New API Key
4. Copy and save the token securely

Keep Your Token Safe

Your API token grants full access to your Timesheet account. Never share it publicly or commit it to version control.

---

Installation

Claude Desktop

Claude Desktop is the most popular way to use the Timesheet MCP server.

Step 1: Locate Configuration File

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 2: Add Timesheet Server

Open the configuration file and add the Timesheet MCP server:

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

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop to load the new configuration.

Step 4: Verify Connection

Ask Claude: "What's my timer status?" If configured correctly, Claude will check your Timesheet account and respond with your current timer state.

---

VS Code with Continue

Continue is an open-source AI coding assistant for VS Code that supports MCP.

Step 1: Install Continue Extension

1. Open VS Code Extensions (Ctrl+Shift+X / Cmd+Shift+X)
2. Search for "Continue"
3. Install the Continue extension

Step 2: Configure MCP Server

Open Continue settings and add the Timesheet server to your configuration:

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

Step 3: Use in Continue

Open the Continue panel and use natural language to control Timesheet while coding.

---

Cursor IDE

Cursor has built-in MCP support for AI-powered development.

Step 1: Open Cursor Settings

Go to Cursor Settings → Features → MCP Servers

Step 2: Add Server Configuration

Add a new MCP server with these settings:

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

Step 3: Enable and Test

Enable the server and test with a simple command like "Check my timer status."

---

Windsurf IDE

Windsurf supports MCP servers for enhanced AI capabilities.

Step 1: Access MCP Configuration

Navigate to Settings → AI → MCP Servers

Step 2: Add Timesheet Server

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

---

Claude Code (CLI)

For developers using Claude Code in the terminal:

Step 1: Create Configuration

Create or edit ~/.claude/settings.json:

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

Step 2: Use in Claude Code

The Timesheet tools will be available in your Claude Code sessions.

---

Global npm Installation (Alternative)

For faster startup, install the package globally:

npm install -g @timesheet/mcp

Then update your configuration to use the installed command:

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

---

Sample Prompts

Once connected, use natural language to control Timesheet. Here are examples organized by task.

Timer Control

Starting Work:

• "Start the timer for ProjectX"
• "Start timer for the mobile app project"
• "Begin tracking time on Website Redesign"
• "Start timer for ProjectX 10 minutes ago" (backdated start)

Stopping Work:

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

Taking Breaks:

• "I'm taking a break"
• "Pause the timer"
• "Taking lunch"
• "I have a meeting, pause my timer"

Resuming Work:

• "Back from break"
• "Resume the timer"
• "Continue working"
• "I'm back, resume timer"

Checking Status:

• "What's my timer status?"
• "Am I tracking time?"
• "Show my current timer"
• "How long have I been working?"

Task Enhancements

Adding Notes:

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

Adding Expenses:

• "Add expense: $45 for lunch with client"
• "Record taxi expense of $25"
• "Log $150 expense for software license"

Updating Current Task:

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

Project Management

Viewing Projects:

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

Creating Projects:

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

Updating Projects:

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

Task History

Viewing Tasks:

• "Show today's tasks"
• "What did I work on yesterday?"
• "List tasks from this week"
• "Show my last 10 time entries"

Creating Manual Entries:

• "Create a 2-hour task for ProjectX from 9am to 11am"
• "Log 4 hours on the API project for yesterday"
• "Add a time entry for Monday, 2 hours on design work"

Updating Tasks:

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

---

Available Tools

The MCP server provides these tools to AI assistants:

Timer Operations

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

Task Enhancements

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

Project Management

Tool	Description
project_list	List projects with optional filters (status, team, search)
project_create	Create a new project
project_update	Update project details or archive
project_delete	Permanently delete a project
project_get	Get detailed information about a specific project

Task Management

Tool	Description
task_list	List time entries with date filters and project filters
task_create	Create a manual time entry for past work
task_update	Modify task details, times, or billing status
task_delete	Delete a time entry
task_get	Get detailed information about a specific task

Team Management

Tool	Description
team_list	List teams for project filtering

Authentication

Tool	Description
auth_configure	Configure API authentication (alternative to environment variable)

---

Best Practices

Be Specific When Needed

Good: "Start timer for the 'Website Redesign' project" Better: (if you have multiple similar projects)

The AI will ask for clarification if your request is ambiguous.

Use Descriptive Notes

When adding notes, be specific enough that you'll understand them later:

• Good: "Add note: Implemented user authentication with JWT tokens"
• Less helpful: "Add note: worked on auth"

Track Expenses Immediately

Add expenses when they occur so you don't forget:

• "Add $35 expense for client lunch at Mario's restaurant"

Review Regularly

Ask the AI for summaries to stay on top of your time:

• "What did I work on this week?"
• "Show me billable hours for this month"
• "How much time did I spend on Project X?"

---

Troubleshooting

Timer Not Starting?

Check these common issues:

1. API Token - Verify your token is correct in the configuration
2. Project Exists - Ensure the project name matches exactly or use the project ID
3. Permissions - Confirm you have access to create tasks for the project
4. Connection - Check that the MCP server is connected (restart your client)

Test connection: Ask "What's my timer status?" - if this fails, there's a configuration issue.

Authentication Errors

Symptoms:

• "Authentication must be configured" error
• "Invalid API token" message
• Tools not responding

Solutions:

1. Verify Token:

   • Go to Timesheet Settings → API Access
   • Generate a new token if needed
   • Update your configuration file

2. Check Configuration:

   • Ensure TIMESHEET_API_TOKEN environment variable is set correctly
   • No extra spaces or quotes around the token
   • File saved and client restarted

3. Token Expiration:

   • API tokens can expire
   • Generate a new token if your old one stopped working

MCP Server Not Found

If you see "command not found" or similar:

1. Check Node.js:

   node --version

   Must be v18 or higher.

2. Check npx:

   npx --version

   Should return a version number.

3. Try Manual Install:

   npm install -g @timesheet/mcp

   Then use timesheet-mcp as the command instead of npx @timesheet/mcp.

Client-Specific Issues

Claude Desktop:

• Restart Claude Desktop after configuration changes
• Check the config file is valid JSON (use a JSON validator)
• Look for Claude Desktop logs for error messages

VS Code/Continue:

• Reload VS Code window after configuration changes
• Check Continue extension is up to date
• Review Continue output panel for errors

General:

• Ensure your client supports MCP (check their documentation)
• Verify the configuration file location is correct for your OS
• Check for conflicting MCP servers

---

Security Considerations

API Token Security

• Never share your API token publicly
• Don't commit tokens to Git repositories
• Use environment variables when possible
• Rotate tokens periodically (generate new one, update config, delete old)

What the MCP Server Can Access

The server can:

• Read and create time entries
• Manage projects you have access to
• Add notes, expenses, and pauses to tasks
• View team information

The server cannot:

• Access other users' private data
• Modify account settings
• Access billing information
• Delete your Timesheet account

Revoking Access

To revoke MCP server access:

1. Go to Timesheet Integrations → API Keys
2. Delete the API token used by the MCP server
3. Remove the server from your MCP client configuration

---

Frequently Asked Questions

Q: Which AI assistants support MCP? A: Claude Desktop, VS Code with Continue, Cursor, Windsurf, Claude Code CLI, and other MCP-compatible tools. ChatGPT support is coming soon.

Q: Do I need to keep Timesheet open? A: No. The MCP server communicates directly with the Timesheet API. You don't need the app or website open.

Q: Can I use this with the mobile app? A: Yes! Time tracked via MCP syncs immediately and appears in the mobile app.

Q: Is there a cost for the MCP server? A: The MCP server itself is free and open source. You need a Timesheet Pro subscription for API access.

Q: Can multiple people use the same MCP server? A: Each person needs their own API token. The MCP server runs locally with your personal token.

Q: Does this work offline? A: No. The MCP server requires an internet connection to communicate with Timesheet.

Q: Can I customize the available commands? A: The commands are fixed, but you can phrase your requests however you like - the AI interprets natural language.

Q: Will my data be sent to AI companies? A: Your Timesheet data is sent to your configured AI provider (e.g., Anthropic for Claude) as context for processing your requests. Review your AI provider's privacy policy.

---

Advanced Configuration

Environment Variables

Configure the MCP server with environment variables:

Variable	Description	Default
TIMESHEET_API_TOKEN	Your Timesheet API token	Required
TIMESHEET_API_URL	Custom API endpoint (for testing)	https://api.timesheet.io

Using with .env File

Create a .env file in your project directory:

TIMESHEET_API_TOKEN=your-api-token-here

The MCP server automatically loads .env files when present.

Development Mode

For local development and testing:

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

# Install dependencies
npm install

# Create .env file with your token
echo "TIMESHEET_API_TOKEN=your-token" > .env

# Run in development mode
npm run dev

---

Getting Help

Support Resources

Timesheet Support:

• Email: support@timesheet.io
• Include: Your MCP client, error messages, configuration (without token)

MCP Documentation:

• Model Context Protocol Specification
• MCP Client Documentation

Package Repository:

• npm: @timesheet/mcp
• GitHub Issues

Reporting Issues

When reporting problems, include:

1. MCP client name and version
2. Operating system
3. Error messages (without your API token)
4. Steps to reproduce the issue
5. What you expected to happen

---

Additional Resources

Timesheet Documentation:

• Plans & Pricing
• Zapier Integration
• QuickBooks Integration
• FAQ

Related Links:

• Model Context Protocol
• Claude Desktop
• Continue for VS Code

---

Ready to control Timesheet with natural language? Get your API token and start using MCP →