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

Related MCP server: mcp-facturacion-electronica-es

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

Products

Ledgers

Inventory

Buyers

Payments

Development

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

License

MIT