Personal Timesheet

A Model Context Protocol (MCP) server that provides CRUD operations for timesheet management via REST API endpoints.

👤 For End Users: See README-USER.md for simple installation instructions
👨‍💻 For Developers: Continue reading below
📦 Publishing: See Publishing Guide to distribute your connector

Features

• Create timesheet entries
• Read timesheet entries (list and get single)
• Update existing entries
• Delete timesheet entries
• List Projects for reference
• Configurable API base URL
• Support for both Go and Node.js backend APIs

Prerequisites

• Node.js 18 or higher
• A running instance of the Timesheet Logger backend API
• Claude Desktop (for integration)

Installation

1. Navigate to the mcp directory:

cd mcp

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env
# Edit .env and set TIMESHEET_API_BASE_URL

4. Build the project:

npm run build

Configuration

Environment Variables

Create a .env file or set environment variables:

TIMESHEET_API_BASE_URL=http://localhost:3000/api

Claude Desktop Integration

Add to your Claude Desktop configuration file:

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

For end users (after publishing to npm):

{
  "mcpServers": {
    "timesheet": {
      "command": "timesheet-mcp",
      "env": {
        "TIMESHEET_API_BASE_URL": "http://localhost:3000/api"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "timesheet": {
      "command": "node",
      "args": ["/absolute/path/to/timesheet_logger/mcp/build/index.js"],
      "env": {
        "TIMESHEET_API_BASE_URL": "http://localhost:3000/api"
      }
    }
  }
}

Usage

Development Mode

Run in development mode with auto-reload:

npm run dev

Production Mode

Build and run:

npm run build
npm start

Available Tools

1. create_timesheet_entry

Create a new timesheet entry.

Parameters:

• project_id (string, required): Project ID
• date (string, required): Entry date (YYYY-MM-DD)
• hours (number, required): Hours worked
• description (string, optional): Entry description
• billable (boolean, optional): Whether entry is billable (default: true)

2. list_timesheet_entries

List timesheet entries with optional filters.

Parameters:

• start_date (string, optional): Filter by start date (YYYY-MM-DD)
• end_date (string, optional): Filter by end date (YYYY-MM-DD)
• project_id (string, optional): Filter by project ID
• limit (number, optional): Maximum results (default: 50)
• offset (number, optional): Offset for pagination (default: 0)

3. get_timesheet_entry

Get a single timesheet entry by ID.

Parameters:

• entry_id (string, required): Entry ID

4. update_timesheet_entry

Update an existing timesheet entry.

Parameters:

• entry_id (string, required): Entry ID
• project_id (string, optional): New project ID
• date (string, optional): New date (YYYY-MM-DD)
• hours (number, optional): New hours
• description (string, optional): New description
• billable (boolean, optional): New billable status

5. delete_timesheet_entry

Delete a timesheet entry.

Parameters:

• entry_id (string, required): Entry ID

6. list_projects

List available projects.

Parameters: None

7. create_project

Create a new project. Requires admin or manager role.

Parameters:

• name (string, required): Project name
• description (string, optional): Project description
• is_active (boolean, optional): Whether project is active (default: true)

8. login

Manually trigger browser-based login. Opens a browser window for authentication.

Parameters: None

Note: Useful after logout or for manual authentication. If already logged in, will show current user.

9. logout

Logout from the current session and clear stored authentication tokens.

Parameters: None

Note: After logout, you will need to re-authenticate (via browser login) on the next request.

Testing

Test with Local Backend

1. Start your backend API:

# From backend/api-nodejs or backend/api-go
docker-compose up

2. Run the MCP server:

npm run dev

3. Test through Claude Desktop or use the MCP Inspector

Troubleshooting

Connection Refused

• Ensure the backend API is running
• Verify the TIMESHEET_API_BASE_URL is correct
• Check that the port matches your backend configuration

Authentication Errors

• Verify API key if required by your backend
• Check that the API endpoint supports the operations

Tool Not Found

• Rebuild the project: npm run build
• Restart Claude Desktop
• Verify the path in Claude Desktop config is absolute

Development

Project Structure

mcp/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── config.ts             # Configuration management
│   ├── types.ts              # TypeScript types
│   ├── api/
│   │   ├── client.ts         # HTTP client wrapper
│   │   └── timesheet.ts      # Timesheet API operations
│   └── tools/
│       ├── create-entry.ts   # Create tool
│       ├── list-entries.ts   # List tool
│       ├── get-entry.ts      # Get tool
│       ├── update-entry.ts   # Update tool
│       └── delete-entry.ts   # Delete tool
├── build/                    # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Adding New Tools

1. Create a new file in src/tools/
2. Define the tool schema using Zod
3. Implement the handler function
4. Register the tool in src/index.ts

License

MIT