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

📋 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 environment variables
SMTP_HOST=smtp.gmail.com [email protected] 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
      - [email protected]
      - SMTP_PASS=your-app-password
      - [email protected]
      - FROM_NAME=Your Company Name

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

2. Configure environment:

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

3. Build and run:

npm run build
npm start

🔧 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": {
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "[email protected]",
        "SMTP_PASS": "your-app-password",
        "FROM_EMAIL": "[email protected]",
        "FROM_NAME": "Your Company Name"
      }
    }
  }
}

For Docker Usage:

{
  "mcpServers": {
    "invoice-server": {
      "command": "docker",
      "args": ["exec", "invoice-mcp-container", "node", "/app/dist/index.js"],
      "env": {
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "[email protected]",
        "SMTP_PASS": "your-app-password"
      }
    }
  }
}

For Local Installation:

{
  "mcpServers": {
    "invoice-server": {
      "command": "node",
      "args": ["/path/to/invoice-mcp-server/dist/index.js"],
      "env": {
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "[email protected]",
        "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 [email protected]

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 [email protected]

🛠️ 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

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | SMTP_HOST | SMTP server host | No* | - | | SMTP_PORT | SMTP server port | No | 587 | | SMTP_USER | SMTP username | No* | - | | SMTP_PASS | SMTP password | No* | - | | FROM_EMAIL | From email address | No | SMTP_USER | | FROM_NAME | From name | No | - | | OUTPUT_DIR | PDF output directory | No | ./invoices | | TEMP_DIR | Temporary files directory | No | /tmp |

*Required only for email functionality

🐳 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 [email protected] \
           -e SMTP_PASS=yourpassword \
           -v $(pwd)/invoices:/app/invoices \
           invoice-mcp-server

🎨 Customization

Modifying the Template

The invoice template is in src/invoice-template.ts. You can customize:

• Styling: Colors, fonts, spacing
• Layout: Header, footer, table structure
• Fields: Add or remove invoice fields
• Branding: Logo, company information

Adding New Features

1. Define new tools in src/index.ts
2. Implement functionality in src/invoice-generator.ts
3. Update documentation

🧪 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
├── dist/                     # Compiled JavaScript
├── invoices/                 # Generated PDFs
├── 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 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

Docker Development

# Build development image
docker build -t invoice-mcp-server:dev .

# Run with volume for development
docker run -v $(pwd):/app -p 3000:3000 invoice-mcp-server:dev

🐛 Troubleshooting

Common Issues

NPX Issues

• Package not found: Ensure you have npm 5.2+ for npx support
• Permission errors: Try sudo npx or fix npm permissions

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

Docker Logs

docker logs invoice-mcp-container

📈 Performance

Optimization Tips

1. Docker Multi-stage builds for smaller images
2. PDF caching for repeated templates
3. Email queuing for bulk operations
4. 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 LICENSE file for details.

🆘 Support

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

Quick Start Example:

1. Run: npx invoice-mcp-server
2. Configure Claude Desktop (see above)
3. Ask Claude: "Create an invoice for ABC Company for $2,500"
4. Claude handles the rest automatically! 🎉

The server handles all formatting, calculations, and delivery automatically.