kmexnx/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-mcp-container", "node", "/app/dist/index.js"],
      "env": {
        "OUTPUT_DIR": "/app/invoices",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "your-email@gmail.com",
        "SMTP_PASS": "your-app-password"
      }
    }
  }
}

For Local Installation:

{
  "mcpServers": {
    "invoice-server": {
      "command": "node",
      "args": ["/path/to/invoice-mcp-server/dist/index.js"],
      "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"
      }
    }
  }
}

💬 Usage Examples

Basic Invoice Creation

Claude, create me an invoice for "Acme Corp" for the amount of $5000

Detailed Invoice

Claude, create an invoice with the following details:
- Client: TechStart Inc.
- Services: Web Development (40 hours at $125/hour), Logo Design ($500)
- Tax rate: 8.5%
- Due date: 30 days from today
- Save as PDF and email to client@techstart.com

Multiple Line Items

Claude, generate an invoice for:
- Company: Global Solutions LLC
- Item 1: Consulting Services - $2,500
- Item 2: Project Management - $1,200
- Item 3: Documentation - $800
- Tax rate: 7.25%
- Email it to accounting@globalsolutions.com

🛠️ Available Tools

1. create_invoice_pdf

Generates a PDF invoice file.

Parameters:

• invoice_data: Complete invoice information
• filename: Optional custom filename

2. send_invoice_email

Creates and sends an invoice via email.

Parameters:

• invoice_data: Complete invoice information
• recipient_email: Email address to send to
• subject: Optional custom email subject
• message: Optional custom email message

3. get_invoice_template

Returns the current invoice template structure for reference.

📊 Invoice Data Structure

{
  // Company Information
  company: {
    name: string;
    address: string;
    city: string;
    state: string;
    zipCode: string;
    phone?: string;
    fax?: string;
    email?: string;
  };
  
  // Client Information
  billTo: {
    name: string;
    company?: string;
    address: string;
    city: string;
    state: string;
    zipCode: string;
    phone?: string;
  };
  
  // Invoice Details
  invoiceNumber: string;
  date: string;
  dueDate?: string;
  
  // Line Items
  items: Array<{
    description: string;
    amount: number;
  }>;
  
  // Financial Details
  taxRate?: number; // as percentage (e.g., 8.5 for 8.5%)
  other?: number;   // additional fees/discounts
}

🔍 Environment Variables

*Required only for email functionality

Important Notes:

• OUTPUT_DIR: Highly recommended to set this to avoid permission issues
• SMTP credentials: Only needed if you want to email invoices
• Paths: Use absolute paths for best results
• Permissions: Ensure the OUTPUT_DIR is writable

🐳 Docker Configuration

Dockerfile

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist ./dist
COPY .env.example ./.env

RUN mkdir -p invoices

EXPOSE 3000

CMD ["node", "dist/index.js"]

Docker Environment

# Run with environment variables
docker run -e SMTP_HOST=smtp.gmail.com \
           -e SMTP_USER=you@gmail.com \
           -e SMTP_PASS=yourpassword \
           -e OUTPUT_DIR=/app/invoices \
           -v $(pwd)/invoices:/app/invoices \
           invoice-mcp-server

🧪 Development

Project Structure

invoice-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── invoice-generator.ts  # PDF generation logic
│   ├── email-service.ts      # Email functionality
│   ├── invoice-template.ts   # HTML template
│   └── setup.js             # Setup script
├── dist/                     # Compiled JavaScript
├── invoices/                 # Generated PDFs (created by setup)
├── Dockerfile               # Docker configuration
├── docker-compose.yml       # Docker Compose setup
├── package.json
└── README.md

NPM Scripts

npm run build      # Compile TypeScript
npm run dev        # Development mode with watch
npm start          # Run compiled server
npm run setup      # Create directories and check setup
npm run clean      # Clean build directory
npm run docker     # Build Docker image

Testing

Test the server using the MCP inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Setup Script

The setup script (npm run setup) will:

• ✅ Create necessary directories
• ✅ Test write permissions
• ✅ Check Node.js version
• ✅ Verify package structure
• ✅ Display helpful diagnostics

🐛 Troubleshooting

Common Issues

Directory Permission Errors

# Solution 1: Set custom directory
export OUTPUT_DIR=/Users/yourname/Documents/invoices
mkdir -p $OUTPUT_DIR

# Solution 2: Use setup script
npm run setup

# Solution 3: Use temporary directory
export OUTPUT_DIR=/tmp/invoices

NPX Issues

• Package not found: Ensure you have npm 5.2+ for npx support
• Permission errors: Try setting OUTPUT_DIR to a directory you own
• Directory creation fails: Use OUTPUT_DIR=/tmp/invoices npx invoice-mcp-server

Docker Issues

• Port conflicts: Change port mapping -p 3001:3000
• Volume issues: Ensure local directories exist and are writable
• Memory limits: Increase Docker memory for large invoices

Email Issues

• Gmail: Use App Passwords instead of regular password
• SMTP Errors: Verify host, port, and credentials
• Firewall: Ensure SMTP ports aren't blocked

PDF Generation Issues

• Missing fonts: Install system fonts or use web fonts
• Memory issues: Increase Node.js memory limit
• Puppeteer errors: Install Chrome dependencies

Debug Mode

Enable debug logging:

DEBUG=invoice-mcp:* npx invoice-mcp-server

Environment Diagnostics

Run the setup script to diagnose issues:

npm run setup

This will show:

• ✅ Directory creation status
• ✅ Write permissions
• ✅ Node.js version
• ✅ Environment information
• ✅ Troubleshooting suggestions

📈 Performance

Optimization Tips

1. Use custom OUTPUT_DIR for faster file access
2. Docker multi-stage builds for smaller images
3. PDF caching for repeated templates
4. Email queuing for bulk operations
5. Resource limits for container deployments

Scaling

• Use Redis for session storage
• Implement queue system for PDF generation
• Load balance multiple containers
• Use external SMTP service

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see file for details.

🆘 Support

• 📋 Issues: GitHub Issues
• 📖 Examples: See
• 📚 MCP Docs: MCP Documentation
• 🐳 Docker: Docker Hub

Quick Start Example:

1. Set your directory: export OUTPUT_DIR=/Users/yourname/Documents/invoices
2. Run: npx invoice-mcp-server
3. Configure Claude Desktop (see above)
4. Ask Claude: "Create an invoice for ABC Company for $2,500"
5. Claude handles the rest automatically! 🎉

The server handles all formatting, calculations, and delivery automatically while saving PDFs to your specified directory.