Invoice MCP Server

Invoice MCP Server

A Model Context Protocol (MCP) server for generating professional invoices as PDFs or sending them via email. This server provides tools that allow Claude to create, customize, and distribute invoices based on a professional template.

🚀 Quick Start

Option 1: NPX (Recommended)

Run directly without installation:

npx invoice-mcp-server

Option 2: Docker

# Pull and run
docker run -p 3000:3000 -v $(pwd)/invoices:/app/invoices invoice-mcp-server

# Or build locally
docker build -t invoice-mcp-server .
docker run -p 3000:3000 -v $(pwd)/invoices:/app/invoices invoice-mcp-server

Option 3: Traditional Installation

git clone https://github.com/kmexnx/invoice-mcp-server.git
cd invoice-mcp-server
npm install
npm run build

✨ Features

• 📄 PDF Generation: Create professional invoices as PDF files
• 📧 Email Integration: Send invoices directly via email
• 🎨 Template-based: Uses a clean, professional invoice template
• 💼 Business Ready: Includes all standard invoice fields (tax rates, line items, etc.)
• 🔧 Customizable: Easy to modify template and styling
• 🐳 Docker Support: Run in containers for easy deployment
• ⚡ NPX Ready: No installation required with npx
• 📁 Smart Directory Handling: Automatic directory creation with fallbacks

📋 Prerequisites

For NPX/Local Installation:

• Node.js 18+
• For email functionality: SMTP server credentials

For Docker:

• Docker installed
• For email functionality: SMTP server credentials

🛠️ Installation & Setup

Method 1: NPX (Zero Installation)

The easiest way to get started:

# Run directly
npx invoice-mcp-server

# With custom output directory
OUTPUT_DIR=/Users/yourname/Documents/invoices npx invoice-mcp-server

# With environment variables
SMTP_HOST=smtp.gmail.com SMTP_USER=you@gmail.com OUTPUT_DIR=/tmp/invoices npx invoice-mcp-server

Method 2: Docker Setup

1. Create a docker-compose.yml:

version: '3.8'
services:
  invoice-mcp:
    image: invoice-mcp-server
    ports:
      - "3000:3000"
    volumes:
      - ./invoices:/app/invoices
      - ./.env:/app/.env
    environment:
      - SMTP_HOST=smtp.gmail.com
      - SMTP_PORT=587
      - SMTP_USER=your-email@gmail.com
      - SMTP_PASS=your-app-password
      - FROM_EMAIL=your-email@gmail.com
      - FROM_NAME=Your Company Name
      - OUTPUT_DIR=/app/invoices

2. Run with Docker Compose:

docker-compose up -d

Method 3: Traditional Installation

1. Clone and install:

git clone https://github.com/kmexnx/invoice-mcp-server.git
cd invoice-mcp-server
npm install
npm run setup  # Creates directories and checks permissions

2. Configure environment:

cp .env.example .env
# Edit .env with your settings

3. Build and run:

npm run build
npm start

📁 Directory Configuration

The server needs a directory to save generated PDF invoices. It uses this priority order:

1. Custom Directory (Recommended): Set OUTPUT_DIR environment variable
2. Default Local: ./invoices in current directory
3. Fallback: System temporary directory

Setting Custom Output Directory

For NPX users:

# Set for current session
export OUTPUT_DIR=/Users/yourname/Documents/invoices
npx invoice-mcp-server

# Or inline
OUTPUT_DIR=/path/to/your/invoices npx invoice-mcp-server

For permanent setup:

Add to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export OUTPUT_DIR=/Users/yourname/Documents/invoices

For Docker users:

docker run -e OUTPUT_DIR=/app/invoices -v /your/local/path:/app/invoices invoice-mcp-server

Directory Permissions

The server automatically:

• ✅ Creates the output directory if it doesn't exist
• ✅ Tests write permissions
• ✅ Falls back to temporary directories if needed
• ✅ Provides clear error messages

If you encounter permission issues:

# Create and set permissions manually
mkdir -p /path/to/your/invoices
chmod 755 /path/to/your/invoices

# Or use a directory you own
export OUTPUT_DIR=$HOME/Documents/invoices

🔧 Claude Desktop Configuration

Add this server to your Claude Desktop configuration:

For NPX Usage:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "invoice-server": {
      "command": "npx",
      "args": ["invoice-mcp-server"],
      "env": {
        "OUTPUT_DIR": "/Users/yourname/Documents/invoices",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "your-email@gmail.com",
        "SMTP_PASS": "your-app-password",
        "FROM_EMAIL": "your-email@gmail.com",
        "FROM_NAME": "Your Company Name"
      }
    }
  }
}

For Docker Usage:

{
  "mcpServers": {
    "invoice-server": {
      "command": "docker",
      "args": ["exec", "invoice-m