hours-mcp by aarlint - MCP Server

Hours MCP - Professional Time Tracking & Invoice Generation

A comprehensive MCP (Model Context Protocol) server that enables contract-based time tracking and professional PDF invoice generation directly through Claude Desktop.

🚀 Quick Start

📦 Download & Install

Download the binary for your platform from Latest Release:

Platform Download
macOS (Apple Silicon) hours-mcp-darwin-arm64
macOS (Intel) hours-mcp-darwin-amd64
Linux (x64) hours-mcp-linux-amd64
Linux (ARM64) hours-mcp-linux-arm64
Windows (x64) hours-mcp-windows-amd64.exe

Platform	Download
macOS (Apple Silicon)	`hours-mcp-darwin-arm64`
macOS (Intel)	`hours-mcp-darwin-amd64`
Linux (x64)	`hours-mcp-linux-amd64`
Linux (ARM64)	`hours-mcp-linux-arm64`
Windows (x64)	`hours-mcp-windows-amd64.exe`

Install the binary:

# Make executable and move to PATH
chmod +x hours-mcp-*
mv hours-mcp-* ~/.local/bin/hours-mcp

Configure Claude Desktop:

Open Claude Desktop → Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "hours": {
      "command": "/Users/YOUR_USERNAME/.local/bin/hours-mcp",
      "args": [],
      "env": {}
    }
  }
}

Replace YOUR_USERNAME with your actual username.

Restart Claude Desktop and start tracking time professionally! 🎯

🎯 First Steps

Configure your business: "Set up my business information"
Add a client: "Add client Acme Corp with address 123 Main St, San Francisco, CA"
Create a contract: "Add contract AC-001 for Acme Corp at $150/hour"
Track time: "Add 2 hours for contract AC-001 today - API development"
Generate invoice: "Create invoice for Acme Corp for this month"

✨ Features

Contract-Based Billing: Professional contract management with individual rates and terms per client engagement
Client Management: Add, edit, and manage clients with complete address information
Time Tracking: Log hours in 15-minute increments against specific contracts with detailed descriptions
Invoice Generation: Create professional PDF invoices with business branding, client addresses, and contract details
Payment Details: Store and manage banking information per client
Recipient Management: Add, list, and remove multiple recipient contacts for each client
Business Information: Configure company details for professional invoice headers
Natural Language Input: Add hours using commands like "add 2 hours for contract CA-001 today"
SQLite Storage: All data stored locally with automatic migrations in ~/.hours/db

Database Schema

The system uses SQLite with the following entity relationships:

erDiagram
    clients {
        int id PK
        string name UK
        string address
        string city
        string state
        string zip_code
        string country
        datetime created_at
        datetime updated_at
    }

    contracts {
        int id PK
        int client_id FK
        string contract_number UK
        string name
        real hourly_rate
        string currency
        string contract_type
        date start_date
        date end_date
        string status
        string payment_terms
        string notes
        datetime created_at
        datetime updated_at
    }

    recipients {
        int id PK
        int client_id FK
        string name
        string email
        string title
        string phone
        boolean is_primary
        datetime created_at
    }

    payment_details {
        int id PK
        int client_id FK "UNIQUE"
        string bank_name
        string account_number
        string routing_number
        string swift_code
        string payment_terms
        string notes
        datetime updated_at
    }

    time_entries {
        string id PK "UUID"
        int client_id FK
        int contract_id FK
        date date
        real hours
        string description
        string contract_ref
        int invoice_id FK
        datetime created_at
    }

    invoices {
        int id PK
        int client_id FK
        string invoice_number UK
        date issue_date
        date due_date
        real total_amount
        string status
        string pdf_path
        datetime created_at
    }

    business_info {
        int id PK "Singleton"
        string business_name
        string contact_name
        string email
        string phone
        string address
        string city
        string state
        string zip_code
        string country
        string tax_id
        string website
        string logo_path
        string invoice_prefix
        datetime updated_at
    }

    migrations {
        int id PK
        string name UK
        datetime applied_at
    }

    clients ||--o{ contracts : "has contracts"
    clients ||--o{ recipients : "has contacts"
    clients ||--o| payment_details : "has payment info"
    clients ||--o{ invoices : "receives invoices"
    contracts ||--o{ time_entries : "tracks hours against"
    invoices ||--o{ time_entries : "includes entries"
    time_entries }o--|| contracts : "billed under"
    time_entries }o--|| clients : "worked for"

Key Database Relationships

Clients are the core entity with complete address information (rates moved to contracts)
Contracts define billing relationships with specific rates, terms, and duration per client engagement
Recipients are contact persons at each client organization (many-to-one with clients)
Payment Details store banking and payment terms information (one-to-one with clients)
Time Entries track billable hours with UUID identifiers linked to both contracts and clients
Invoices group time entries for billing with automatic numbering (many-to-one with clients)
Business Info is a singleton containing your company information for invoice headers
Migrations track database schema changes for safe upgrades

Contract-Based Architecture

The system uses a professional contract-based billing model where:

Each client can have multiple contracts with different rates and terms
Time entries are logged against specific contracts, not just clients
Invoices are generated per contract, allowing separate billing for different engagements
Historical rate changes are preserved through contract versioning

🛠️ Advanced Installation

📥 Pre-built Binaries (Recommended)

See the Quick Start section above for binary downloads.

🔨 Build from Source

For developers who want to build from source:

Prerequisites

Go 1.21 or later
Claude Desktop app
Git

Build Steps

# Clone the repository
git clone https://github.com/aarlint/hours-mcp.git
cd hours-mcp

# Download dependencies
go mod download

# Build for your platform
make build

# Or build for all platforms
make build-all

# Install to ~/.local/bin
make install

⚙️ Claude Desktop Configuration Details

Configuration File Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Complete Configuration Example

{
  "mcpServers": {
    "hours": {
      "command": "/Users/YOUR_USERNAME/.local/bin/hours-mcp",
      "args": [],
      "env": {}
    }
  }
}

Troubleshooting Configuration

Replace YOUR_USERNAME with your actual system username
Ensure the binary path is correct: which hours-mcp
Verify binary is executable: chmod +x ~/.local/bin/hours-mcp
Check Claude Desktop logs if connection fails
Restart Claude Desktop after configuration changes

Verification

After restarting Claude Desktop, you should be able to use commands like:

"List all clients"
"Set up my business information"
"Add client Test Corp"

Usage Examples

Client & Contract Management

"Add client Acme Corp with address 123 Business St, San Francisco, CA 94102"
"Edit client Acme Corp to update address to 456 New Street, Los Angeles, CA 90210"
"List all clients"
"Add contract AC-2025-001 for Acme Corp with rate $150/hour for Backend Development"
"List contracts for Acme Corp"
"Add recipient John Doe john@acmecorp.com for Acme Corp with title CTO"
"List recipients for Acme Corp"
"Remove recipient ID 5"
"Set payment details for Acme Corp: Bank of America, Net 30"

Time Tracking

"Add 2 hours for contract AC-2025-001 today"
"Add 8 hours for contract AC-2025-001 this week"
"Add 4.5 hours for contract AC-2025-001 yesterday with description 'Backend API development'"
"List hours for this month"
"Show all hours for Acme Corp last week"
"Search time entries for contract AC-2025-001"

Invoice Generation

"Create invoice for Acme Corp for this month"
"Make invoice for ClientX for last month"
"Create invoice for January 2025 for Acme Corp"
"List all pending invoices"
"Show invoice INV-202501-abc12345"

Natural Language Time Entry

The MCP supports flexible natural language input:

Contract-based entries: "Add 2 hours for contract CA-001 today"
Time periods: "today", "yesterday", "this week", "last week", "this month"
Hour increments: Supports 0.25 (15 min), 0.5 (30 min), 0.75 (45 min), etc.
Bulk entries: "Add 8 hours for contract CA-001 this week" adds 8 hours to each weekday
Detailed descriptions: All entries support rich descriptions for work performed

Data Storage

All data is stored in SQLite at ~/.hours/db with the following structure:

Clients with complete address information
Contracts with individual rates, terms, and status per client engagement
Recipients for each client with management capabilities
Payment details per client
Time entries linked to both contracts and clients
Generated invoices with PDF storage

PDF Invoice Output

Invoices are generated as PDFs and saved to ~/Downloads/invoice_YYYY-MM-DD.pdf

Each invoice includes:

Business header with company information
Client information and billing address
Contract details (number, name, rate, terms)
Itemized time entries with dates, descriptions, hours, and amounts
Total hours and amount calculation
Recipient contact information
Payment details and banking information
Due date (default: Net 30)

Professional Features

Single-contract billing for clean, focused invoices
Automatic rate calculation from contract terms
Complete audit trail with time entry UUIDs
Professional formatting suitable for client delivery

Development

# Run tests
make test

# Run locally for development
make run

# Clean build artifacts
make clean

License

MIT