Which integrations are available for this server?

Enables sending generated invoices via email by configuring Gmail's SMTP server settings.

How do I use Invoice MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Invoice MCP Server generate an invoice for 5 consulting hours at $150/hr and email it to client@example.com" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

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

Run with Docker Compose:

docker-compose up -d

Method 3: Traditional Installation

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

Configure environment:

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

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:

Custom Directory (Recommended): Set OUTPUT_DIR environment variable
Default Local: ./invoices in current directory
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

Variable	Description	Required	Default	Example
`OUTPUT_DIR`	PDF output directory	Recommended	`./invoices`	`/Users/name/Documents/invoices`
`SMTP_HOST`	SMTP server host	No*	-	`smtp.gmail.com`
`SMTP_PORT`	SMTP server port	No	`587`	`587`
`SMTP_USER`	SMTP username	No*	-	`you@gmail.com`
`SMTP_PASS`	SMTP password	No*	-	`your-app-password`
`FROM_EMAIL`	From email address	No	`SMTP_USER`	`billing@company.com`
`FROM_NAME`	From name	No	-	`Your Company Name`
`TEMP_DIR`	Temporary files directory	No	System temp	`/tmp`

*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

Use custom OUTPUT_DIR for faster file access
Docker multi-stage builds for smaller images
PDF caching for repeated templates
Email queuing for bulk operations
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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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:

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

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