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

npm install

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:

# Backend API (optional - defaults to https://timesheet.pinnacle.in:3000/api)
API_BASE_URL=https://timesheet.pinnacle.in:3000/api

# Node Environment
NODE_ENV=production

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

3. Build and Run

npm run build
npm run start

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:

{
  "success": true,
  "message": "✓ User authenticated successfully!",
  "data": {
    "user": {
      "id": 41,
      "name": "John Doe",
      "username": "john.doe@company.com",
      "email": "john.doe@company.com",
      "roles": ["RESOURCE"],
      "managerId": 44
    },
    "projects": [
      {
        "id": 9,
        "name": "Project Name",
        "project_id": 9
      }
    ],
    "modules": [
      {
        "id": 41,
        "name": "Pyramid2.0_UI Gateway",
        "project_id": 9
      }
    ]
  }
}

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:

{
  "project_id": 9,
  "module_id": 41,
  "activity_id": 11,
  "start_time": "09:00:00",
  "end_time": "10:00:00",
  "duration": 60,
  "description": "Working on user authentication module implementation",
  "date": "2025-11-04"
}

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:

{
  "page": 1,
  "limit": 10
}

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:

{
  "success": true,
  "message": "✓ Available work activities fetched successfully!",
  "data": [
    {
      "id": 1,
      "name": "Development",
      "description": "Development work"
    },
    {
      "id": 11,
      "name": "Code Review",
      "description": "Code review activities"
    }
  ]
}

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:

{
  "date": "2025-11-04",
  "yesterdays_progress": "Completed user authentication module with tests",
  "todays_priorities": "Implement profile page and integrate with API",
  "task_blockers": "Waiting for backend API documentation"
}

MCP Client Configuration

For Claude Desktop

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

{
  "mcpServers": {
    "timesheet-mcp": {
      "command": "node",
      "args": ["/path/to/timesheet-mcp/dist/main.js"],
      "env": {
        "NODE_ENV": "production",
        "API_BASE_URL": "https://timesheet.pinnacle.in:3000/api",
        "TIMESHEET_USERNAME": "your.email@company.com",
        "TIMESHEET_PASSWORD": "your-password"
      }
    }
  }
}

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:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "timesheet-mcp": {
      "type": "local",
      "command": ["node", "/path/to/timesheet-mcp/dist/main.js"],
      "enabled": true,
      "environment": {
        "NODE_ENV": "production",
        "API_BASE_URL": "https://timesheet.pinnacle.in:3000/api",
        "TIMESHEET_USERNAME": "your.email@company.com",
        "TIMESHEET_PASSWORD": "your-password"
      }
    }
  }
}

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

For MCP Inspector

npm run inspector

Architecture

src/
├── common/                           # Shared utilities and DTOs
│   └── utils/
│       └── response.util.ts         # MCP response formatting utility
├── auth/                            # Authentication module
│   ├── auth.module.ts
│   ├── auth.service.ts
│   ├── auth.tools.ts               # whoami tool
│   ├── auto-login.service.ts
│   └── dto/
│       └── login.dto.ts
├── projects/                        # Project management module
│   ├── projects.module.ts
│   ├── projects.service.ts
│   └── projects.tools.ts           # Project-related tools
├── timesheets/                      # Timesheet module
│   ├── timesheets.module.ts
│   ├── timesheets.service.ts
│   ├── timesheets.tools.ts         # Timesheet creation and listing tools
│   └── dto/
│       └── create-timesheet.dto.ts
├── activities/                      # Activity management module
│   ├── activities.module.ts
│   ├── activities.service.ts
│   └── activities.tools.ts         # Activity listing tool
├── daily-updates/                   # Daily scrum module
│   ├── daily-updates.module.ts
│   ├── daily-updates.service.ts
│   ├── daily-updates.tools.ts      # Daily scrum tool
│   └── dto/
│       └── create-daily-scrum.dto.ts
├── config/                          # Configuration management
├── shared/                          # HTTP client & shared utilities
├── main.ts                          # Application entry point
└── app.module.ts                    # Main application module

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