Skip to main content
Glama
morenoraf

Invoice MCP Server

by morenoraf
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Invoice MCP Server

A Model Context Protocol (MCP) server for invoice management with modular architecture.

Documentation

Related MCP server: mcp-ai-fiskalizacija

Features

  • MCP Protocol Support: Full implementation of Tools, Resources, and Prompts

  • Multiple Transports: STDIO and HTTP/SSE support

  • Dual GUI: CLI and Web interfaces

  • SDK Layer: All operations through unified SDK

  • Modular Design: Swappable components without code changes

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      GUI Layer                              │
│              ┌─────────┐    ┌─────────┐                     │
│              │   CLI   │    │   Web   │                     │
│              └────┬────┘    └────┬────┘                     │
├───────────────────┴──────────────┴──────────────────────────┤
│                      SDK Layer                              │
│   CustomerOperations │ InvoiceOperations │ ReportOperations │
├─────────────────────────────────────────────────────────────┤
│                    MCP Server                               │
│   ┌─────────┐    ┌───────────┐    ┌─────────┐              │
│   │  Tools  │    │ Resources │    │ Prompts │              │
│   └─────────┘    └───────────┘    └─────────┘              │
├─────────────────────────────────────────────────────────────┤
│                  Transport Layer                            │
│              ┌─────────┐    ┌─────────┐                     │
│              │  STDIO  │    │  HTTP   │                     │
│              └─────────┘    └─────────┘                     │
├─────────────────────────────────────────────────────────────┤
│                 Infrastructure                              │
│     Database │ Repositories │ Lock Manager │ Config         │
└─────────────────────────────────────────────────────────────┘

Quick Start

# 1. Clone and install
git clone <repository-url>
cd MCP_Server
pip install -e ".[dev]"

# 2. Test the CLI
python -m invoice_mcp_server cli customer list

# 3. Run the MCP server
python -m invoice_mcp_server stdio

Installation

Requirements

  • Python 3.10+

  • pip

Install for Development

# Install with dev dependencies (pytest, mypy, ruff)
pip install -e ".[dev]"

Install for Production

pip install -e .

Configuration

All configuration via environment variables or .env file:

# Server
SERVER_HOST=127.0.0.1
SERVER_PORT=8080

# Database
DB_PATH=data/invoices.db

# Invoice
VAT_RATE=0.17
CURRENCY=ILS

# Transport
TRANSPORT_TYPE=stdio

# Logging
LOG_LEVEL=INFO

Running the Server

MCP Server (STDIO) - For MCP Clients

python -m invoice_mcp_server stdio

Use this mode when connecting from Claude Desktop or other MCP clients.

MCP Server (HTTP)

python -m invoice_mcp_server http

Web Interface

python -m invoice_mcp_server web
# Access at http://localhost:8080

Help

python -m invoice_mcp_server --help

CLI Reference

The CLI provides direct access to all operations for testing and management.

Customer Commands

# List all customers
python -m invoice_mcp_server cli customer list

# Create a new customer
python -m invoice_mcp_server cli customer create --name "Acme Corp" --email "contact@acme.com"

# Create with all fields
python -m invoice_mcp_server cli customer create --name "Acme Corp" --email "contact@acme.com" --address "123 Main St" --phone "555-1234"

# Delete a customer
python -m invoice_mcp_server cli customer delete <customer-id>

Invoice Commands

# List all invoices
python -m invoice_mcp_server cli invoice list

# Create a new invoice
python -m invoice_mcp_server cli invoice create --customer-id <customer-id>

# Create with due date and notes
python -m invoice_mcp_server cli invoice create --customer-id <customer-id> --due-date "2024-12-31" --notes "Project payment"

# Add item to invoice
python -m invoice_mcp_server cli invoice add-item --invoice-id <invoice-id> --description "Consulting services" --quantity 10 --price 150.00

# Send invoice
python -m invoice_mcp_server cli invoice send <invoice-id>

# Record payment
python -m invoice_mcp_server cli invoice pay --invoice-id <invoice-id> --amount 1500.00 --method "bank_transfer"

Report Commands

# Show statistics
python -m invoice_mcp_server cli report stats

# Show overdue invoices
python -m invoice_mcp_server cli report overdue

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "invoice-server": {
      "command": "python",
      "args": ["-m", "invoice_mcp_server", "stdio"],
      "cwd": "/path/to/MCP_Server"
    }
  }
}

Testing MCP Connection

You can test the MCP server by sending JSON-RPC messages via stdio:

# Start the server and send an initialize request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | python -m invoice_mcp_server stdio

MCP Primitives

Tools (Write Operations)

  • create_customer - Create new customer

  • update_customer - Update customer details

  • delete_customer - Delete customer

  • create_invoice - Create new invoice

  • add_invoice_item - Add item to invoice

  • update_invoice_status - Change invoice status

  • record_payment - Record payment

  • send_invoice - Send invoice to customer

Resources (Read Operations)

  • invoice://config - Server configuration

  • invoice://vat-rates - VAT rates

  • invoice://customers/list - Customer list

  • invoice://invoices/list - Invoice list

  • invoice://invoices/recent - Recent invoices

  • invoice://invoices/overdue - Overdue invoices

  • invoice://statistics/overview - Statistics

Prompts (Model Guidance)

  • create_invoice - Guide for invoice creation

  • manage_customer - Guide for customer management

  • process_payment - Guide for payment processing

  • generate_report - Guide for report generation

Testing

Run All Tests

pytest

Run with Coverage Report

pytest --cov=src/invoice_mcp_server --cov-report=term-missing

Run Specific Test Files

# Test models
pytest tests/test_models.py -v

# Test database
pytest tests/test_database.py -v

# Test SDK
pytest tests/test_sdk.py -v

# Test MCP server
pytest tests/test_mcp_server.py -v

Run Tests by Pattern

# Run all customer-related tests
pytest -k "customer" -v

# Run all invoice-related tests
pytest -k "invoice" -v

Code Quality

# Type checking
mypy src/invoice_mcp_server

# Linting
ruff check src/invoice_mcp_server

# Format check
ruff format --check src/invoice_mcp_server

Example Workflow

# 1. Create a customer
python -m invoice_mcp_server cli customer create --name "Test Company" --email "test@company.com"
# Returns: {"id": "uuid-here", "name": "Test Company", ...}

# 2. List customers to get the ID
python -m invoice_mcp_server cli customer list

# 3. Create an invoice for the customer
python -m invoice_mcp_server cli invoice create --customer-id <customer-id-from-step-2>

# 4. Add items to the invoice
python -m invoice_mcp_server cli invoice add-item --invoice-id <invoice-id> --description "Service" --quantity 1 --price 100

# 5. Check statistics
python -m invoice_mcp_server cli report stats

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-ai-fiskalizacija

    Seyn-Labs
    A
    license
    A
    quality
    C
    maintenance
    MCP server for creating and fiscalizing invoices via solo.com.hr API. Enables AI agents to generate invoices, retrieve invoice details, list invoices, and check next invoice number.
    4
    MIT

  • agent-invoice

    nyx-builds
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables agents to generate, track, and manage invoices via MCP tools, with CLI support for payment tracking and earnings summaries.
    MIT

  • myinvois-mcp

    techtemplemy
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables issuing and managing validated Malaysian e-invoices via MyInvois (LHDN) directly from MCP clients, with tools for TIN validation, invoice drafting, submission, and document management.
    473 npm
    2
    Do What The F*ck You Want To Public