Timesheet MCP Server

An MCP (Model Context Protocol) server that automatically generates timesheets by collecting activity data from GitLab/GitHub and calendar services (Google Calendar and Outlook Calendar).

Features

• GitLab Integration: Tracks commits, merge requests, code reviews, issue comments, and status changes
• GitHub Integration: Tracks commits, pull requests, code reviews, issue activity
• Dual Git Support: Use GitLab, GitHub, or both simultaneously
• Google Calendar Integration: Fetches meeting information (prioritized)
• Outlook Calendar Integration: Fallback calendar source
• Smart Scheduling: Automatically skips Saturdays (except first Saturday) and Sundays
• LLM-Powered Summarization: Returns complete data; LLM intelligently summarizes to 255 characters per day
• Intelligent Work Distribution: LLM distributes work descriptions across light-activity days
• Multiple Timesheet Formats: Monthly, weekly, daily, and custom date range
• Activity Caching: Speeds up repeated queries with smart caching
• Secure Token Storage: Stores authentication tokens securely in your home directory
• OAuth2 Support: Proper authentication flows with token refresh for calendar services

Installation

1. Install Dependencies

npm install

2. Build the Project

npm run build

3. Configure API Credentials

Create Configuration File

Copy the template and fill in your credentials:

cp config.template.json ~/.timesheet-mcp-config.json

Edit ~/.timesheet-mcp-config.json with your actual credentials:

{
  "gitlab": {
    "url": "https://gitlab.com"
  },
  "google": {
    "clientId": "YOUR_GOOGLE_CLIENT_ID",
    "clientSecret": "YOUR_GOOGLE_CLIENT_SECRET",
    "redirectUri": "http://localhost:3000/oauth/callback"
  },
  "outlook": {
    "clientId": "YOUR_OUTLOOK_CLIENT_ID",
    "clientSecret": "YOUR_OUTLOOK_CLIENT_SECRET",
    "tenantId": "YOUR_TENANT_ID",
    "redirectUri": "http://localhost:3000/oauth/callback"
  }
}

Note: Calendar configuration is optional. GitLab and/or GitHub tokens are configured through the MCP tools.

Get GitLab Personal Access Token

1. Go to GitLab → User Settings → Access Tokens
2. Create a token with read_api and read_repository scopes
3. You'll configure this token through the MCP tool (see Usage section)

Get GitHub Personal Access Token

1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Tokens (classic)
2. Generate new token with repo and read:user scopes
3. You'll configure this token through the MCP tool (see Usage section)

Get Google Calendar Credentials (Optional)

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Google Calendar API
4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client ID"
5. Configure OAuth consent screen
6. Create credentials for "Desktop app" or "Web application"
7. Copy Client ID and Client Secret to config file

Get Outlook Calendar Credentials (Optional)

1. Go to Azure Portal
2. Register a new application in Azure AD
3. Add redirect URI: http://localhost:3000/oauth/callback
4. Go to "Certificates & secrets" → Create a new client secret
5. Go to "API permissions" → Add Calendars.Read permission
6. Copy Application (client) ID, Client Secret, and Directory (tenant) ID to config file

4. Configure Claude Desktop or Claude Code

Add the MCP server to your Claude configuration.

For Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "timesheet": {
      "command": "node",
      "args": ["/absolute/path/to/timsheetmcp/build/index.js"]
    }
  }
}

For Claude Code (VS Code Extension)

Edit ~/.config/claude-code/config.json or use VS Code settings:

{
  "mcpServers": {
    "timesheet": {
      "command": "node",
      "args": ["/absolute/path/to/timsheetmcp/build/index.js"]
    }
  }
}

Important: Replace /absolute/path/to/timsheetmcp with the actual absolute path to your installation.

Usage

First Time Setup

After configuring the MCP server in Claude, restart Claude and then:

1. Check Authentication Status

Can you check my timesheet authentication status?

2. Configure GitLab and/or GitHub

Configure at least one Git service:

Configure GitLab with token: YOUR_GITLAB_TOKEN

Configure GitHub with token: YOUR_GITHUB_TOKEN

You can configure both if you use both platforms.

3. Configure Google Calendar (Optional)

Set up Google Calendar authentication

Claude will provide an authorization URL. Visit it, authorize the app, and copy the authorization code. Then:

Complete Google Calendar auth with code: YOUR_AUTH_CODE

4. Configure Outlook Calendar (Optional)

Set up Outlook Calendar authentication

Follow the same OAuth flow as Google Calendar.

Generate Timesheets

Once configured, you can generate timesheets with simple commands:

Monthly Timesheet

Generate timesheet for this month

Generate timesheet for March 2024

Generate timesheet for 2024-03

Weekly Timesheet

Generate timesheet for this week

Generate timesheet for last week

Generate timesheet for the week of 2024-11-24

Daily Timesheet

Generate timesheet for today

Generate timesheet for yesterday

Generate timesheet for 2024-11-21

Custom Date Range

Generate timesheet from 2024-11-01 to 2024-11-15

Output Format

The MCP server returns raw, untruncated data with complete information about all activities. The LLM (Claude) then:

1. Intelligently summarizes each day to fit within 255 characters while preserving meaning
2. Distributes work from heavy activity days to light activity days for a coherent narrative
3. Formats the final timesheet

What's Included

• Date and Day: Each working day in the period
• Meetings: List of attended meetings (from calendars)
• Git Activity (GitLab/GitHub):
  • Commits with messages and projects
  • Merge/Pull requests (created, reviewed, approved, commented)
  • Issue activity (comments, status changes, assignments)
• Character Count: Shows character count to ensure it's within 255-character limit

Example Output

## 2024-11-01 (Friday)
Attended Sprint Planning, Team Standup. Committed "feat: user auth" to ProjectX; "fix: API bug" to ProjectY. Created MR #123 in ProjectX. Reviewed PR #456 in ProjectZ.
*Character count: 182/255*

## 2024-11-04 (Monday)
Attended Daily Standup. Made 3 commits to ProjectX: "impl login flow", "add auth tests", "fix linting". Approved MR #789 in ProjectY. Commented on issue #234 in ProjectX.
*Character count: 189/255*

Working Days Logic

The MCP server automatically:

• Includes all weekdays (Monday-Friday)
• Includes the first Saturday of each month
• Excludes all Sundays
• Excludes all other Saturdays

PSI Timesheet Integration

The MCP server now supports automatic submission to PSI Project Server (SharePoint-based) timesheet systems.

Setup

1. Configure PSI credentials:

   Configure PSI with username: YOUR_USERNAME and password: YOUR_PASSWORD

2. Optional: Specify custom URL (embeds credentials in URL):

   Configure PSI with username: YOUR_USERNAME, password: YOUR_PASSWORD, and url: https://YOUR_USERNAME:[email protected]/PWA/_layouts/15/pwa/Timesheet/MyTSSummary.aspx

Usage Workflow

1. Generate timesheet:

   Generate timesheet for this week

2. Inspect PSI page (first time):

   Inspect PSI page structure

   This reveals the grid object, methods, and available buttons for customization.

3. Submit to PSI:

   Submit the timesheet entries to PSI

How It Works

• Uses Puppeteer for browser automation with HTTP Basic Auth support
• Handles SharePoint Project Server's grid-based timesheet interface
• Automatically detects grid objects (idGrid, g_grid, pwaGrid)
• Attempts multiple methods to fill timesheet data
• Supports multiple save/submit button patterns

Important Notes

⚠️ SharePoint Grid Complexity: PSI Project Server uses a JavaScript-based grid system. The integration attempts to:

• Find the grid object using common variable names
• Call grid methods like AddRow(), SetValue(), etc.
• Submit using various button selectors and JavaScript functions

⚠️ Customization May Be Required: If your PSI instance uses different:

• Grid variable names
• Method names for adding/updating rows
• Button IDs or submission functions

You can inspect the page structure using inspect_psi_page and modify src/integrations/psi.ts accordingly.

Browser Mode

By default, the browser opens in non-headless mode (headless: false) so you can see what's happening. For production use, change this to headless: true in src/integrations/psi.ts:15.

Caching

• Activity data is cached to improve performance
• Use force_refresh: true parameter to bypass cache and fetch fresh data
• Cache can be cleared using the clear_cache tool

Security

• Tokens are stored in ~/.timesheet-mcp-tokens.json with restricted file permissions (600)
• PSI credentials are stored securely in the token file
• OAuth tokens are automatically refreshed when expired
• Configuration file should be kept secure and not committed to version control
• Never share your tokens or commit them to version control
• PSI passwords can be embedded in URLs for authentication (HTTP Basic Auth)

Troubleshooting

"Configuration file not found" error

Make sure you've created ~/.timesheet-mcp-config.json with your API credentials (at minimum an empty JSON object {}).

"Neither GitLab nor GitHub configured" error

Use the configure_gitlab or configure_github tool through Claude to set up at least one Git service.

Calendar authentication expired

Re-run the OAuth flow using the configure_google_calendar or configure_outlook_calendar tools.

No activities showing up

• Verify your GitLab/GitHub token has correct permissions
• Check that you've authorized calendar access (if using calendars)
• Ensure the date range is correct
• Verify you had actual activity during that period
• Try using force_refresh: true to bypass cache

MCP server not showing up in Claude

1. Verify the path in your config is absolute and correct
2. Run npm run build to ensure the project is built
3. Restart Claude Desktop or VS Code
4. Check Claude's MCP server logs for errors

Development

Watch Mode

npm run watch

Manual Testing

npm run dev

Tools Available

The MCP server exposes these tools to Claude:

Timesheet Generation

1. generate_timesheet: Generate monthly timesheet from GitLab/GitHub and calendar activities
2. generate_weekly_timesheet: Generate weekly timesheet
3. generate_daily_timesheet: Generate single-day timesheet
4. generate_date_range_timesheet: Generate timesheet for custom date range

Service Configuration

5. configure_gitlab: Set up GitLab personal access token
6. configure_github: Set up GitHub personal access token
7. configure_google_calendar: Start Google Calendar OAuth flow
8. google_calendar_callback: Complete Google Calendar OAuth
9. configure_outlook_calendar: Start Outlook Calendar OAuth flow
10. outlook_calendar_callback: Complete Outlook Calendar OAuth
11. configure_psi: Configure PSI Project Server timesheet integration
12. check_authentication_status: Check authentication status for all services

PSI Timesheet Submission

13. submit_to_psi: Submit generated timesheet entries to PSI Project Server
14. inspect_psi_page: Inspect PSI page structure for debugging

Utilities

15. clear_cache: Clear cached activity data

Technical Details

• Language: TypeScript
• Runtime: Node.js
• Protocol: Model Context Protocol (MCP)
• Git APIs: GitBeaker (GitLab), Octokit (GitHub)
• Calendar APIs: Google Calendar API, Microsoft Graph API
• Caching: File-based activity cache with TTL

License

MIT

Contributing

Contributions are welcome! Please feel free to:

• Report bugs by opening issues
• Suggest new features
• Submit pull requests with improvements
• Improve documentation

Changelog

v1.1.0 - 2025-12-05

• NEW: PSI Project Server Integration
  • Added browser automation with Puppeteer for SharePoint authentication
  • Smart grid detection and interaction for SharePoint PWA timesheets
  • HTTP Basic Auth support with credential embedding in URLs
  • New tools: configure_psi, submit_to_psi, inspect_psi_page
  • Enhanced page inspection with grid method/property detection
• Updated authentication status to include PSI
• Improved documentation with PSI setup and usage workflows

v1.0.0 - 2024-11-27

• Initial release with GitLab and GitHub integration
• Support for Google Calendar and Outlook Calendar
• Multiple timesheet formats (monthly, weekly, daily, custom range)
• LLM-powered intelligent summarization and work distribution
• Activity caching for improved performance