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
- Authentication:
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:
- On Server Startup: Config file is deleted to ensure a clean state
- On Every Tool Call:
- Attempts to use existing cached token (if available)
- Automatically refreshes token via
/auth/refreshendpoint - If token is expired or invalid, re-authenticates using
TIMESHEET_USERNAMEandTIMESHEET_PASSWORDfrom MCP client environment - If login fails, returns a clear error message
- 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 tomodule_id(number): Which module/component within the projectactivity_id(number): The type of work (Development, Code Review, Testing, etc.)start_time(string): Start time in HH:MM:SS formatend_time(string): End time in HH:MM:SS formatduration(number): Duration in minutesdescription(string, min 10 chars): Detailed work descriptiondate(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 paginationlimit(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 formatyesterdays_progress(string): Summary of work completed yesterdaytodays_priorities(string): Main priorities and goals for todaytask_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 authenticationGET /api/projects/user/{userId}- Get user projectsGET /api/modules/by-project?projectId={id}- Get project modulesGET /api/activities- Get all activitiesPOST /api/timesheets/create- Create timesheet entryGET /api/timesheets/list/{userId}- Get user timesheets
License
MIT