Tallied MCP server

Tallied

Tallied is a time-tracking and invoicing MCP server. It's connector-first: Claude and ChatGPT (or any MCP client) are the primary UI — you tell an assistant what you worked on and it logs the hours, ask what's unbilled and it drafts the invoice. A minimal web app handles the things chat is bad at: account settings, CSV import, and billing. Clients pay invoices through a Stripe payment link on a public, tokenized page.

Claude / ChatGPT / MCP client
        │  MCP over Streamable HTTP (OAuth 2.1 bearer token)
        ▼
┌───────────────────────────────────────────────┐
│  one origin (BASE_URL)                         │
│  /mcp            MCP endpoint                  │
│  /authorize /token /register /revoke           │
│                   OAuth 2.1 authorization server│
│  /app/*          web app (settings, import,     │
│                   billing)                      │
│  /i/<token>      public invoice page + PDF      │
└───────────────────────────────────────────────┘
        │                    │                │
        ▼                    ▼                ▼
    Postgres              Stripe        SMTP / Resend
 (workspaces, entries,  (subscriptions,  (magic links,
  invoices, tokens,      payment links)   invoice emails)
  audit log)
                                          pdfkit (invoice PDFs, in-process)

Quick start

cp .env.example .env
npm install
npm run db:up          # postgres via docker compose, localhost:5433
npm run db:migrate     # applies src/db/schema.sql idempotently
npm run db:seed        # seeds a demo workspace; prints the login email
# In production (compiled image, no tsx): node dist/scripts/seed.js reviewer@withtallied.com
npm run build:app      # builds the MCP App UI bundle into app/dist/app.html
npm run dev            # tsx watch src/index.ts

Then connect with the MCP Inspector:

npm run inspector

Choose Streamable HTTP, point it at http://localhost:3000/mcp, and connect. The inspector will hit the OAuth flow and open the login page in your browser. Without SMTPURL or RESENDAPI_KEY set, magic-link sign-in doesn't send an email — the link is printed to the server log and also shown directly on the "check your email" page, so local dev never needs a real mailbox.

Project layout

src/
  index.ts       entry point
  config.ts      env vars, plans, scopes
  db/            schema.sql, migration runner, query helpers
  lib/           dates, duration parsing, rates, ids, errors, money
  services/      workspace, time entries, invoices, propose (catch-up), audit
  mcp/           McpServer setup: tools, resources, prompts (src/mcp/server.ts)
  auth/          OAuth provider, login/consent routes, sessions, Google OIDC
  http/          express app, docs/marketing routes, web app routes, invoice pages
  import/        CSV import (Toggl/Harvest/Clockify)
  stripe/        billing checkout, Connect onboarding, webhook handling
  email/         email sending via SMTP (nodemailer) or Resend (magic links, invoice emails)
  pdf/           invoice PDF rendering (pdfkit)
app/             MCP App UI source; scripts/build-app.ts bundles it into app/dist/app.html,
                 which src/mcp/app-resource.ts embeds as an MCP UI resource and
                 src/http/routes/invoice-public.ts reuses for the public invoice page
skills/          bundled Claude skills (log-day, catch-up, weekly-report,
                 invoice-client, month-close) — also exposed as MCP prompts
.cla

Environment variables

Shortened. The full README is on GitHub.