simple_invoicing-mcp

MCP (Model Context Protocol) server that acts as a bridge to any deployed simple_invoicing FastAPI instance.

This server exposes the simple_invoicing REST API as MCP tools, making it usable directly from Claude Desktop, Cursor, or any other MCP-compatible client.

Prerequisites

• Node.js ≥ 18
• A running simple_invoicing FastAPI backend
• A long-lived bearer token (API token) for the backend

Setup

git clone https://github.com/nikhilb2/simple_invoicing-mcp.git
cd simple_invoicing-mcp
npm install
npm run build

Configuration

Set these environment variables before running:

export INVOICING_BASE_URL=https://your-invoicing-instance.example.com
export INVOICING_API_TOKEN=your-long-lived-bearer-token-here

Or copy .env.example to .env and fill in the values.

How to get an API token

1. Open your simple_invoicing backend's Swagger UI (usually at /docs)
2. Use the /api/auth/login endpoint with your credentials
3. Copy the access_token from the response
4. Use this token as INVOICING_API_TOKEN

Running locally (dev)

npm run dev

This starts the MCP server on stdio using tsx.

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "invoicing": {
      "command": "node",
      "args": ["/absolute/path/to/simple_invoicing-mcp/dist/index.js"],
      "env": {
        "INVOICING_BASE_URL": "https://invoicing.example.com",
        "INVOICING_API_TOKEN": "your-token-here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "invoicing": {
      "command": "node",
      "args": ["/absolute/path/to/simple_invoicing-mcp/dist/index.js"],
      "env": {
        "INVOICING_BASE_URL": "https://invoicing.example.com",
        "INVOICING_API_TOKEN": "your-token-here"
      }
    }
  }
}

Available Tools

Invoices

Tool	Description	Parameters
list_invoices	List all invoices with optional filtering	invoice_type? ("sales"|"purchase"), skip?, limit?
get_invoice	Get a single invoice by ID	id (number)
create_invoice	Create a new invoice	data (object)
get_invoice_pdf	Get the PDF for an invoice	id (number)

Products

Tool	Description	Parameters
list_products	List all products	skip?, limit?
get_product	Get a single product by ID	id (number)
create_product	Create a new product	data (object)

Ledgers

Tool	Description	Parameters
list_ledgers	List all ledgers	skip?, limit?
get_ledger_statement	Get the statement for a ledger	id, start_date?, end_date?
get_day_book	Get the day book entries	start_date?, end_date?

Inventory

Tool	Description	Parameters
list_inventory	List all inventory items	skip?, limit?

Buyers

Tool	Description	Parameters
list_buyers	List all buyers	skip?, limit?
get_buyer	Get a single buyer by ID	id (number)

Payments

Tool	Description	Parameters
list_payments	List all payments	skip?, limit?
create_payment	Create a new payment	data (object)

Development

npm install      # Install dependencies (set NODE_ENV=development for devDeps)
npm run build    # Compile TypeScript
npm test         # Run tests

License

MIT