Claude Code invoice generator: bill from hours.csv or git log

Connect the FreeInvoices server

FreeInvoices runs a remote MCP server at https://freeinvoices.app/mcp. It uses the Streamable HTTP transport and needs no sign-in or API key. Claude Code's docs recommend HTTP for remote servers, so this is the standard form:

claude mcp add --transport http freeinvoices https://freeinvoices.app/mcp

Pick a scope: local, project or user

claude mcp add takes a --scope flag. Without it, the server is added at local scope.

• local (default): only you, only the current project. Stored in ~/.claude.json.
• project: shared with your team through version control. Written to .mcp.json in the project root.
• user: only you, but available in every project. Stored in ~/.claude.json.

# every project you work on
claude mcp add --transport http --scope user freeinvoices https://freeinvoices.app/mcp

# this repo, shared with teammates via .mcp.json
claude mcp add --transport http --scope project freeinvoices https://freeinvoices.app/mcp

Share it with a team using .mcp.json

The project-scope command writes a .mcp.json file at the repo root. You can also create it by hand. For an HTTP server the entry needs type as well as url. The docs say an entry with a url but no type is read as a stdio server and skipped.

Commit the file and teammates get the server when they open the project. In interactive sessions, Claude Code asks each person to approve a project-scoped server before using it. claude mcp reset-project-choices clears those answers.

{
  "mcpServers": {
    "freeinvoices": {
      "type": "http",
      "url": "https://freeinvoices.app/mcp"
    }
  }
}

Check that it connected

Run claude mcp list to see each server with its health status, or claude mcp get freeinvoices for one server. Inside a session, /mcp shows the same status. To undo the setup, run claude mcp remove freeinvoices.

The server exposes one tool, create_document. It is read-only: it builds a link to a pre-filled document and totals, stores nothing, and logs no arguments.

Worked example: invoice a client from hours.csv

A freelancer keeps a time log. Claude Code can read the file, group rows into line items, and call create_document. The grouping and wording are the part worth reviewing, so ask for line items by task rather than one line per day.

Here is the October log, hours.csv:

date,task,hours
2026-10-02,Fix checkout rounding bug,3.5
2026-10-06,Stripe webhook retry handling,4
2026-10-09,Stripe webhook retry handling,2.5
2026-10-14,Admin dashboard filters,6
2026-10-20,Admin dashboard filters,5.5
2026-10-27,Code review and deploy support,2

What Claude Code sends and what comes back

Prompt: "Read hours.csv and invoice Northwind Goods for October at $95/hour, Net 15, from Sam Rivera. One line item per task." Claude Code groups the 23.5 hours into four items and calls the tool with arguments like these:

{
  "type": "invoice",
  "number": "2026-10",
  "date": "2026-10-31",
  "paymentTerms": "Net 15",
  "from": "Sam Rivera\nSam Rivera Software LLC",
  "billTo": "Northwind Goods\nAccounts Payable",
  "currency": "USD",
  "items": [
    { "description": "Checkout rounding bug fix (Oct 2)", "quantity": 3.5, "rate": 95 },
    { "description": "Stripe webhook retry handling (Oct 6, 9)", "quantity": 6.5, "rate": 95 },
    { "description": "Admin dashboard filters (Oct 14, 20)", "quantity": 11.5, "rate": 95 },
    { "description": "Code review and deploy support (Oct 27)", "quantity": 2, "rate": 95 }
  ],
  "notes": "Hours from hours.csv, billed at 95 USD per hour."
}

Check the totals before you send

We ran these arguments against the server. The reply included a link that opens the invoice pre-filled, and these totals: subtotal 2,232.50, no discount, tax or shipping, total 2,232.50, balance due 2,232.50 USD. That matches 23.5 hours times 95. Open the link, add your logo, and click Download PDF.

Invoice from git log instead

If you do not keep a time log, Claude Code can read the month's commits. Commits record what changed, not how long it took, so you supply the hours or a day rate and check the result.

• Ask it to run git log --since=2026-10-01 --until=2026-11-01 --author="Sam" --oneline and group commits by feature.
• Give it the basis for quantity: hours per group, or days worked at a day rate.
• Tell it to list any group where it had to guess, so you can fix those lines.
• Put a ticket or repo reference in the line description if the client expects one.

Make it repeatable with a skill

Claude Code's docs say custom commands have been merged into skills: a file at .claude/commands/invoice.md and a skill at .claude/skills/invoice/SKILL.md both create /invoice. Personal skills go in ~/.claude/skills/<name>/SKILL.md, project skills in .claude/skills/<name>/SKILL.md. $ARGUMENTS expands to whatever you type after the command.

---
description: Create a monthly client invoice from hours.csv using the freeinvoices MCP server
argument-hint: [client] [YYYY-MM]
---

Read hours.csv and keep only rows for the month in $ARGUMENTS.
Group rows by task into line items (quantity is hours, rate is 95 USD).
Call the freeinvoices create_document tool with type invoice, Net 15.
Reply with the link and the totals, and list any rows you could not place.

Standing instructions in CLAUDE.md

To keep details like your address and rate out of every prompt, put them in a project CLAUDE.md (at ./CLAUDE.md or ./.claude/CLAUDE.md) or in ~/.claude/CLAUDE.md for all projects. Claude treats these as context, not enforced rules, so still read the output.

## Invoicing
- Sender: Sam Rivera, Sam Rivera Software LLC
- Rate: 95 USD per hour, terms Net 15
- Time log: hours.csv (columns date, task, hours)
- To invoice, use the freeinvoices MCP server's create_document tool

Privacy

Anthropic sees what Claude Code reads and sends in the session, including your CSV or commit messages. When it calls create_document, the invoice details go to freeinvoices.app/mcp to build the link and are not stored. The document data in the link sits in the URL fragment after #, which browsers do not send to servers. Do not paste client secrets into a time log you plan to share.