paper-invoice-mcp

MCP (Model Context Protocol) server for Paper.id — Indonesian invoicing & accounting platform.

Exposes 31 tools covering partner CRUD, invoice CRUD, send invoice, QRIS payment, and reporting.
Token is persisted in SQLite and auto-refreshed on 401 — no manual token management needed.

Quick Setup

Option A — JWT token only

Best for quick testing or CI. No password stored — just paste your token.

1. Get your token from Chrome DevTools:

Open app.paper.id → DevTools (F12) → Network tab
Click any request to api.paper.id → Headers → Request Headers
Copy the value after Authorization: Bearer (the eyJ... part)

2. Get your Company ID and User ID:

Same DevTools window → Response tab of any request
Look for body.user.uuid (User ID) and body.user.company_id (Company ID)
Or: set PAPERID_TOKEN first, then call tool paperid_get_current_user — it returns both

3. Add to your MCP client config:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "paperid": {
      "command": "node",
      "args": ["/absolute/path/to/paper-invoice-mcp/dist/index.js"],
      "env": {
        "PAPERID_TOKEN":      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your.token",
        "PAPERID_COMPANY_ID": "37e0eae0-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "PAPERID_USER_ID":    "3f5a9896-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json)

{
  "mcpServers": {
    "paperid": {
      "command": "node",
      "args": ["/absolute/path/to/paper-invoice-mcp/dist/index.js"],
      "env": {
        "PAPERID_TOKEN":      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your.token",
        "PAPERID_COMPANY_ID": "37e0eae0-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "PAPERID_USER_ID":    "3f5a9896-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "paperid": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/paper-invoice-mcp/dist/index.js"],
      "env": {
        "PAPERID_TOKEN":      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your.token",
        "PAPERID_COMPANY_ID": "37e0eae0-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "PAPERID_USER_ID":    "3f5a9896-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

JWT expires in ~30 days. When it does, copy a fresh token from DevTools and update the config.
Full step-by-step with troubleshooting: examples/jwt-only.md

Option B — Phone + Password (auto-refresh)

Best for long-running assistants. Token saved to SQLite, silently refreshed on 401.

Claude Desktop / Cursor / VS Code:

{
  "mcpServers": {
    "paperid": {
      "command": "node",
      "args": ["/absolute/path/to/paper-invoice-mcp/dist/index.js"],
      "env": {
        "PAPERID_PHONE":    "08xxxxxxxxxx",
        "PAPERID_PASSWORD": "your_password_here"
      }
    }
  }
}

First run — call paperid_login (or paperid_refresh_token) once to store the JWT in SQLite.
After that, the server handles everything automatically.

Token persisted at ~/.paperid-mcp/tokens.db. Override path with PAPERID_DB_PATH.

Features

Partner management — create, read, list, search, update, delete
Invoice management — create, read, list, send (WA/email/SMS), generate QRIS, delete
Notes & Terms — notes (Keterangan) and terms (Syarat & Ketentuan) support plain text or HTML
Token persistence — JWT stored in SQLite (~/.paperid-mcp/tokens.db)
Auto token refresh — re-logins on 401 when PAPERID_PHONE + PAPERID_PASSWORD are set
Reporting — account receivable/payable insights, profit & loss

Requirements

Node.js ≥ 18 (uses built-in FormData)
Bun (recommended) or npm

Installation

git clone git@github.com:igun997/paper-invoice-mcp.git
cd paper-invoice-mcp
bun install
bun run build

Configuration

Create a .env file (or set environment variables):

# Required for auto token refresh
PAPERID_PHONE=08xxxxxxxxxx
PAPERID_PASSWORD=your_password_here

# Optional overrides (loaded from SQLite if omitted)
PAPERID_TOKEN=            # JWT token (leave blank to use SQLite)
PAPERID_COMPANY_ID=       # Company UUID
PAPERID_USER_ID=          # User UUID

# Optional: custom SQLite path (default: ~/.paperid-mcp/tokens.db)
PAPERID_DB_PATH=/path/to/tokens.db

Security: Never commit .env to version control. The .gitignore excludes it.

Token Lifecycle

First run: PAPERID_PHONE + PAPERID_PASSWORD set
    → paperid_login  (or paperid_refresh_token tool)
    → JWT saved to SQLite

Subsequent runs:
    → JWT loaded from SQLite automatically
    → On 401: re-login silently, retry request

Manual refresh:
    → Call paperid_refresh_token tool
    → Or: set PAPERID_TOKEN env var for one-time use

MCP Client Configuration

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "paperid": {
      "command": "node",
      "args": ["/absolute/path/to/paper-invoice-mcp/dist/index.js"],
      "env": {
        "PAPERID_PHONE": "08xxxxxxxxxx",
        "PAPERID_PASSWORD": "your_password_here"
      }
    }
  }
}

Cursor / VS Code (`.cursor/mcp.json` or `.vscode/mcp.json`)

{
  "mcpServers": {
    "paperid": {
      "command": "node",
      "args": ["/absolute/path/to/paper-invoice-mcp/dist/index.js"],
      "env": {
        "PAPERID_PHONE": "08xxxxxxxxxx",
        "PAPERID_PASSWORD": "your_password_here"
      }
    }
  }
}

Using Bun directly

{
  "mcpServers": {
    "paperid": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/paper-invoice-mcp/src/index.ts"],
      "env": {
        "PAPERID_PHONE": "08xxxxxxxxxx",
        "PAPERID_PASSWORD": "your_password_here"
      }
    }
  }
}

Available Tools (31 total)

Auth & Token

Tool	Description
`paperid_login`	Login with phone + password
`paperid_refresh_token`	Re-login and update SQLite token
`paperid_get_token_info`	Check token expiry (does not expose raw JWT)
`paperid_get_current_user`	Get authenticated user info

Partners

Tool	Description
`paperid_get_partners`	List partners with pagination
`paperid_search_partners`	Search partners by name
`paperid_get_partner`	Get partner by UUID
`paperid_create_partner`	Create new partner
`paperid_update_partner`	Update existing partner
`paperid_delete_partner`	Delete partner
`paperid_get_partner_contacts`	Get partner contacts
`paperid_get_partner_bank_accounts`	Get partner bank accounts
`paperid_get_next_partner_number`	Get next auto-generated partner number

Invoices

Tool	Description
`paperid_get_sales_invoices`	List invoices with filters + pagination
`paperid_create_invoice`	Create invoice (supports notes + terms)
`paperid_get_invoice`	Get invoice by UUID
`paperid_get_invoice_pdf`	Get invoice PDF data
`paperid_send_invoice`	Send via WhatsApp / Email / SMS
`paperid_generate_invoice_qris`	Generate QRIS payment QR code
`paperid_delete_invoice`	Delete invoice

Reporting

Tool	Description
`paperid_get_account_receivable`	AR insight (unpaid, overdue)
`paperid_get_account_payable`	AP insight
`paperid_get_profit_loss`	Profit & Loss report
`paperid_get_company`	Company details
`paperid_get_kyc_status`	KYC verification status
`paperid_get_user_package`	Subscription package info
`paperid_get_onboarding_status`	Onboarding completion
`paperid_get_referral_link`	Referral code & link
`paperid_get_notifications`	User notifications
`paperid_get_dashboard_todos`	Dashboard to-do list
`paperid_get_banners`	Promotional banners

Usage Examples

Create Invoice with Notes & Terms

{
  "tool": "paperid_create_invoice",
  "arguments": {
    "partner_id": "uuid-of-partner",
    "partner_name": "PT Mitra Sejati",
    "number": "INV/2026/0012",
    "invoice_date": "2026-05-14",
    "due_date": "2026-06-13",
    "items": [
      {
        "item_name": "Jasa Konsultasi",
        "item_description": "Konsultasi IT bulan Mei 2026",
        "quantity": 1,
        "price": 5000000
      }
    ],
    "notes": "Transfer ke BCA 1234567890 a/n PT Cipta Dua Saudara",
    "terms": "Pembayaran jatuh tempo 30 hari. Keterlambatan dikenakan denda 2%/bulan.",
    "status": 4
  }
}

notes and terms accept plain text (auto-wrapped in <p> tags) or raw HTML.

Send Invoice via WhatsApp

{
  "tool": "paperid_send_invoice",
  "arguments": {
    "invoiceId": "uuid-of-invoice",
    "whatsapp": { "number": "6281234567890" }
  }
}

Refresh Token

{
  "tool": "paperid_refresh_token",
  "arguments": {}
}

Returns expiry info. Raw JWT is never returned by any tool.

MCP Resources

The server exposes 6 resources AI clients can read for accurate tool usage:

URI	Description
`paperid://docs/overview`	Overview, tool groups, typical workflow
`paperid://docs/auth`	Login flow, SQLite persistence, auto-refresh
`paperid://docs/jwt-only`	JWT-only setup, config examples, expiry handling
`paperid://docs/partners`	Partner schema, field types, phone format, base paths
`paperid://docs/invoices`	Invoice schema, line items, notes/terms, status codes
`paperid://docs/api-reference`	All 31 HTTP endpoints with methods and paths

Project Structure

paper-invoice-mcp/
├── src/
│   ├── index.ts              # Entrypoint — connects MCP server to stdio
│   ├── server-factory.ts     # createMcpServer() — all tools, handlers, resources
│   ├── client.ts             # Paper.id API client (axios)
│   └── token-store.ts        # SQLite token persistence (better-sqlite3)
├── examples/
│   └── jwt-only.md           # JWT-only setup guide (step-by-step + all client configs)
├── .github/
│   └── workflows/ci.yml      # CI: build+resources (all PRs), e2e (merge to master)
├── dist/                     # Compiled JS (gitignored)
├── .env.example              # Sample env vars (no real credentials)
├── tsconfig.json
└── package.json

Development

bun run build     # Compile TypeScript → dist/
bun run dev       # Run with tsx (no compile step)

SQLite Schema

CREATE TABLE tokens (
  phone       TEXT PRIMARY KEY,
  token       TEXT NOT NULL,
  user_id     TEXT NOT NULL,
  company_id  TEXT NOT NULL,
  expires_at  INTEGER NOT NULL,  -- Unix timestamp
  created_at  INTEGER NOT NULL,
  updated_at  INTEGER NOT NULL
);

Token auto-refreshes when expired (with 5-minute buffer) if credentials are in env.

License

MIT