Timesheet MCP Server

Simple timesheet automation server using Model Context Protocol (MCP) and NestJS.

Features

• Fresh Token on Every Tool Call - Automatically refreshes authentication token on each request

• Smart Authentication Handling - Seamlessly handles token expiration and re-authenticates using MCP client credentials

• No Token Storage - Config file is deleted on server startup for security; fresh login on every session

• Stateless Operation - Each tool call is independent and self-authenticating

• 5 Essential Tools organized by domain:

  • Authentication: whoami - Get current user info, assigned projects, and modules

  • Timesheets: create_new_timesheet_entry, list_user_timesheet_entries

  • Activities: list_all_available_work_activities

  • Daily Updates: create_daily_scrum_standup_update

Quick Setup

1. Install Dependencies

2. Configure Environment

The server requires credentials to be configured in your MCP client's environment variables (not in a .env file on the server). This ensures credentials are never stored on the server.

TIMESHEET_USERNAME and TIMESHEET_PASSWORD must be configured in your MCP client configuration:

• For Claude Desktop: Configure in claude_desktop_config.json (see below)

• For OpenCode: Configure in the MCP environment variables

• For MCP Inspector: Set as environment variables before running

Optional server-side .env file:

Note: SSL certificate verification is automatically disabled in the code for self-signed certificates.

3. Build and Run

Authentication

The server implements stateless, fresh authentication for every tool call:

1. On Server Startup: Config file is deleted to ensure a clean state

2. On Every Tool Call:

   • Attempts to use existing cached token (if available)

   • Automatically refreshes token via /auth/refresh endpoint

   • If token is expired or invalid, re-authenticates using TIMESHEET_USERNAME and TIMESHEET_PASSWORD from MCP client environment

   • If login fails, returns a clear error message

3. No Token Persistence: Tokens are saved to config file temporarily but deleted on next server restart

This approach ensures:

• ✅ Fresh authentication on every server session

• ✅ Automatic token refresh without user intervention

• ✅ Graceful handling of expired credentials

• ✅ Clear error messages for troubleshooting

• ✅ No sensitive data stored on disk between sessions

Available Tools

Authentication Tools

whoami

Get current authenticated user information with automatically fetched projects and modules. This tool:

• Handles authentication automatically (refreshes token or logs in with MCP client credentials)

• Returns fresh user details, all assigned projects, and modules within those projects

• Provides clear error messages if credentials are missing or invalid

• This is the primary starting tool for verifying authentication

Parameters: None

Response:

Timesheet Management Tools

create_new_timesheet_entry

Create a new daily timesheet entry with work details.

Parameters:

• project_id (number): Which project the work belongs to

• module_id (number): Which module/component within the project

• activity_id (number): The type of work (Development, Code Review, Testing, etc.)

• start_time (string): Start time in HH:MM:SS format

• end_time (string): End time in HH:MM:SS format

• duration (number): Duration in minutes

• description (string, min 10 chars): Detailed work description

• date (string): Date in YYYY-MM-DD format

Example:

list_user_timesheet_entries

Fetch and display user's timesheet entries with pagination.

Parameters:

• page (number, optional, default: 1): Page number for pagination

• limit (number, optional, default: 10, max: 100): Number of entries per page

Example:

Activity Management Tools

list_all_available_work_activities

Get all available work activity types/categories that can be used when creating timesheet entries.

Parameters: None

Response:

Daily Updates Tools

create_daily_scrum_standup_update

Create a daily scrum standup update to report progress and blockers.

Parameters:

• date (string): Date in yyyy-MM-dd format

• yesterdays_progress (string): Summary of work completed yesterday

• todays_priorities (string): Main priorities and goals for today

• task_blockers (string): Any blockers or impediments (or "None" if no blockers)

Example:

MCP Client Configuration

For Claude Desktop

Create/edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or appropriate config file for your OS:

Windows Claude Desktop Path: %APPDATA%\Claude\claude_desktop_config.json Linux Claude Desktop Path: ~/.config/claude/claude_desktop_config.json

For OpenCode

Edit your OpenCode config file and add the MCP server configuration:

Note: The "type": "local" field is required for OpenCode to recognize the MCP server.

For MCP Inspector

Architecture

Design Principles

• Modular Architecture: Each domain (auth, projects, timesheets, etc.) is a separate module

• Separation of Concerns: Services handle business logic, tools handle MCP interface

• Descriptive Tool Names: Tool names clearly indicate what they do for LLM decision making

• Response Utility: Centralized MCP response formatting for consistency

• DTOs: Type-safe data transfer between layers

Philosophy

This MCP server provides simple API wrappers - no AI, no smart parsing, no complex workflows.

The LLM (Claude, GPT, etc.) handles all natural language processing and intelligence. The server just provides CRUD operations for the timesheet API.

API Endpoints Used

• POST /api/auth/login - User authentication

• GET /api/projects/user/{userId} - Get user projects

• GET /api/modules/by-project?projectId={id} - Get project modules

• GET /api/activities - Get all activities

• POST /api/timesheets/create - Create timesheet entry

• GET /api/timesheets/list/{userId} - Get user timesheets

License

MIT