Invoice MCP Server

A standalone Model Context Protocol (MCP) Server for the Invoice Generator application. This server bridges an AI Client (like Claude, Cursor, ChatGPT) with an existing Express.js/Supabase backend, allowing the AI to authenticate and interact with invoices.

Features

• login: Authenticates against the backend and stores the JWT securely in-memory.

• create_invoice: Searches for a client by name and creates a new invoice for them.

• download_invoice: Retrieves the download link/stream for a specific invoice.

Related MCP server: InvoiceNinja MCP Server

Setup and Installation

1. Install dependencies:

   npm install

2. Environment Variables: Ensure you have a .env file at the root of the project with the following variable:

   API_BASE_URL=https://suriyainvoicegenerator.in

   Replace the URL with your actual backend URL.

Running Locally

To run the server locally for testing:

npm start

Note: The server uses stdio for MCP communication, so it will wait for stdin messages rather than acting as an HTTP server.

Registering the MCP Server

You can register this MCP server in your AI client. For example, in Cursor, go to Settings -> Features -> MCP, and add a new server with the following command:

node /absolute/path/to/invoice-mcp-server/src/index.js

(Make sure to use the absolute path to your src/index.js file.)

Architecture & Folder Structure

mcp-server/
├── src/
│   ├── index.js                  # Entry point, sets up stdio transport
│   ├── server.js                 # Registers MCP server and routes tool requests
│   ├── config/
│   │   └── env.js                # Environment variable configuration (dotenv & Zod)
│   ├── services/
│   │   └── api.js                # Axios client and in-memory session manager
│   ├── tools/
│   │   ├── login.js              # Tool for backend authentication
│   │   ├── createInvoice.js      # Tool for creating an invoice
│   │   └── downloadInvoice.js    # Tool for downloading an invoice
│   ├── middleware/
│   │   └── errorHandler.js       # Centralized error handler returning MCP errors
│   └── utils/
│       ├── logger.js             # Basic logger (hides sensitive data)
│       └── response.js           # MCP response formatting utilities
├── package.json
├── .env
└── README.md

Sample Prompts

Once registered with your AI client, try prompts like:

• "Login to the invoice generator with email user@example.com and password mypassword."

• "Create an invoice for Acme Corp with 2 Laptops at 45000 each. The invoice date is today and due in 30 days."

• "Download invoice number 12345 and give me the link."