Invoices

Open Source — GitScrum MCP Server is open source under the MIT license. Available on npm and GitHub. Model Context Protocol server for GitScrum — Claude, GitHub Copilot, Cursor, and any MCP-compatible client full operational access to your project management stack.

The invoice tool provides 8 actions covering the complete billing lifecycle — from creating draft invoices through sending, tracking payment, and handling cancellations. Every billing operation available in the GitScrum web application is accessible through natural language conversation with your AI assistant.

Invoices in GitScrum follow a strict status lifecycle. Each invoice progresses through defined states, and the MCP Server enforces these transitions automatically. Your AI assistant can create itemized invoices, send them to clients, record payments, and generate billing analytics — all without leaving your IDE or AI client.

Actions Overview

Status Lifecycle

Every invoice follows a defined status progression. The MCP Server enforces valid transitions — you cannot mark a draft invoice as paid without sending it first, and cancelled invoices cannot be reopened.

  ┌───────┐      send      ┌──────┐     mark_paid    ┌──────┐
  │ Draft │ ──────────────► │ Sent │ ────────────────► │ Paid │
  └───────┘                 └──────┘                   └──────┘
      │                         │
      │       cancel            │        (auto)
      │◄────────────────────    │──────────────────►  ┌─────────┐
      │                         │    past due_date    │ Overdue │
      ▼                         ▼                     └─────────┘
  ┌───────────┐           ┌───────────┐                    │
  │ Cancelled │           │ Cancelled │                    │ cancel
  └───────────┘           └───────────┘                    ▼
                                                     ┌───────────┐
                                                     │ Cancelled │
                                                     └───────────┘

• Draft — Initial state. Editable. Can be sent or cancelled.
• Sent — Delivered to client. Transitions to paid, overdue, or cancelled.
• Paid — Payment recorded. Terminal state.
• Overdue — Automatically set when a sent invoice passes its due date.
• Cancelled — Terminated. Terminal state.

Listing Invoices

The list action returns invoices within a workspace. Filter by status or client to narrow results.

Required Parameters

Optional Parameters

Example Prompts

You:  "Show all invoices"
AI:   Calls invoice action=list → returns invoice list with status and amounts

You:  "List unpaid invoices"
AI:   Calls invoice action=list with status="sent"

You:  "Show overdue invoices"
AI:   Calls invoice action=list with status="overdue"

You:  "List all invoices for Acme Corp"
AI:   Finds client UUID → calls invoice action=list with client_uuid

Getting Invoice Details

The get action returns the complete invoice — title, client, line items, amounts, tax, dates, status, and payment history.

Required Parameters

You:  "Show me invoice details for the Acme Corp website project"
AI:   Finds invoice → calls invoice action=get → returns full invoice with line items

You:  "What's the total on our latest invoice?"
AI:   Lists recent invoices → calls invoice action=get → extracts total amount

Creating Invoices

The create action builds a new draft invoice. You can include line items, tax rates, client association, and currency in a single call. The invoice starts in Draft status, allowing review and edits before sending.

Required Parameters

Optional Parameters

Line Items Structure

Each item in the items array follows this structure:

Example Prompts

You:  "Create an invoice for Acme Corp: Website Redesign, $5,000, due March 15"
AI:   Finds client UUID → calls invoice action=create with title="Website Redesign",
      client_uuid, items=[{description: "Website Redesign", quantity: 1, unit_price: 5000}],
      due_date="2026-03-15"

You:  "Invoice TechStart for 40 hours of development at $150/hour plus 10% tax"
AI:   Calls invoice action=create with title, client_uuid,
      items=[{description: "Development Services", quantity: 40, unit_price: 150}],
      tax_rate=10

You:  "Create an invoice with three line items:
       - UX Design: 20 hours at $120
       - Frontend Dev: 60 hours at $150
       - QA Testing: 15 hours at $100"
AI:   Calls invoice action=create with items array containing all three entries

Updating Invoices

The update action modifies a draft invoice. Only invoices in Draft status can be updated — once sent, the invoice is locked.

Required Parameters

All optional parameters from create are available in update.

You:  "Add a 10% tax to the Acme Corp invoice"
AI:   Calls invoice action=update with tax_rate=10

You:  "Change the due date to April 1"
AI:   Calls invoice action=update with due_date="2026-04-01"

You:  "Update the invoice notes: 'Net 30 payment terms'"
AI:   Calls invoice action=update with notes="Net 30 payment terms"

Sending Invoices

The send action transitions an invoice from Draft to Sent. This delivers the invoice to the client and locks it from further edits. The status change is recorded with a timestamp.

Required Parameters

You:  "Send the Acme Corp invoice"
AI:   Calls invoice action=send → invoice transitions from Draft to Sent

You:  "Send all draft invoices"
AI:   Lists draft invoices → calls invoice action=send for each

Recording Payment

The mark_paid action records payment on a sent or overdue invoice. You can optionally specify the payment date and method for accounting records.

Required Parameters

Optional Parameters

You:  "Mark the Acme Corp invoice as paid"
AI:   Calls invoice action=mark_paid → invoice transitions to Paid

You:  "Record payment for invoice, received yesterday via bank transfer"
AI:   Calls invoice action=mark_paid with payment_date="2026-02-05",
      payment_method="Bank transfer"

You:  "Mark all overdue invoices from TechStart as paid"
AI:   Lists overdue invoices for client → calls mark_paid for each

Cancelling Invoices

The cancel action terminates an invoice. This works on invoices in Draft, Sent, or Overdue status. You can optionally provide a reason for the cancellation.

Required Parameters

Optional Parameters

You:  "Cancel the draft invoice for Global Media"
AI:   Calls invoice action=cancel → invoice transitions to Cancelled

You:  "Cancel invoice with reason: 'Project scope changed, new invoice to follow'"
AI:   Calls invoice action=cancel with reason

Billing Statistics

The stats action returns workspace-level billing metrics — total invoiced amount, paid vs outstanding, overdue totals, average payment time, and revenue trends. These numbers power the billing dashboard in the GitScrum web application.

Required Parameters

You:  "Show billing stats"
AI:   Calls invoice action=stats → returns total invoiced, paid, outstanding, overdue

You:  "How much revenue is outstanding?"
AI:   Calls invoice action=stats → extracts outstanding invoice total

You:  "What's our average payment time?"
AI:   Calls invoice action=stats → returns average days to payment

Billing Workflow

For agencies managing multiple client engagements, this workflow covers the complete billing lifecycle:

1. Create the invoice

Build an itemized invoice linked to a client.

You:  "Create an invoice for Acme Corp: Phase 1 delivery — 80 hours frontend at $150,
       20 hours design at $120, 10% tax, due March 30"
AI:   Single create call with all line items, tax, and due date

2. Review and adjust

Check the draft before sending.

You:  "Show me the Acme Corp invoice"
AI:   Calls invoice action=get → displays full invoice for review

You:  "Add a note: 'Payment via bank transfer to account ending 4521'"
AI:   Calls invoice action=update with notes

3. Send to client

Deliver the invoice.

You:  "Send the Acme Corp invoice"
AI:   Calls invoice action=send → invoice is delivered and locked

4. Track payment

Monitor for payment and record when received.

You:  "Any overdue invoices?"
AI:   Calls invoice action=list with status="overdue" → shows overdue items

You:  "Acme Corp paid their invoice via wire transfer"
AI:   Calls invoice action=mark_paid with payment_method="Wire transfer"

5. Review billing health

Monitor overall billing performance.

You:  "Show me the billing overview"
AI:   Calls invoice action=stats → summarizes revenue, outstanding, and payment trends

Next Steps

• Clients: Manage client records linked to your invoices.
• Proposals: Create proposals that convert into invoiced projects.
• ClientFlow Dashboards: Access billing analytics and cross-workspace reports.
• Projects: Manage project delivery alongside billing.