@elyonar/einvoice-mcp

MCP (Model Context Protocol) server for the E-Invoice platform. Enables AI agents like Claude to manage invoices, sellers, buyers, and billing through a tax-authority-compliant e-invoicing system.

Quick Start

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "einvoice": {
      "command": "npx",
      "args": ["-y", "@elyonar/einvoice-mcp"],
      "env": {
        "EINVOICE_API_KEY": "sk_live_your_key_here",
        "EINVOICE_BASE_URL": "https://api.einvoice.ng"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | EINVOICE_API_KEY | Yes | API key (sk_live_... or sk_test_...) | | EINVOICE_BASE_URL | No | API gateway URL (default: https://api.einvoice.ng) | | EINVOICE_REQUEST_TIMEOUT | No | Request timeout in ms (default: 30000) | | EINVOICE_RETRY_ATTEMPTS | No | Max retries for failed requests (default: 3) |

Available Tools (41)

Invoice Tools (15)

• create_invoice — Create a new invoice in draft status
• get_invoice — Get invoice details by ID
• list_invoices — List/filter/search invoices
• update_invoice — Update a draft invoice
• delete_invoice — Delete a draft invoice
• submit_invoice — Submit to tax authority
• batch_submit_invoices — Batch submit multiple invoices
• retry_invoice_submission — Retry a failed submission
• cancel_invoice — Cancel an accepted invoice (creates credit note)
• get_invoice_status — Get status from local DB
• query_invoice_status — Query tax authority for real-time status
• validate_invoice — Validate without creating
• download_invoice — Get PDF/XML download URL
• get_invoice_statistics — Analytics and metrics
• get_invoice_setup — Reference data for invoice creation

Seller Tools (7)

• create_seller — Register a new seller
• get_seller — Get seller details
• list_sellers — List/search sellers
• update_seller — Update seller (tax number immutable)
• delete_seller — Delete seller (no invoices)
• verify_seller_tax_no — Trigger tax number verification
• get_seller_tax_verification_status — Check tax verification status

Buyer Tools (7)

• create_buyer — Register a new buyer
• get_buyer — Get buyer details
• list_buyers — List/search buyers
• update_buyer — Update buyer (tax number immutable)
• delete_buyer — Delete buyer (no invoices)
• verify_buyer_tax_no — Trigger tax number verification
• get_buyer_tax_verification_status — Check tax verification status

Billing Tools (12)

• get_billing_account — Credit balance and account status
• check_balance — Verify sufficient credits before operations
• get_billing_setup — Full billing overview
• get_subscription_plans — Available subscription plans
• get_credit_packages — Available credit packages for purchase
• get_active_subscription — Current subscription details
• get_subscription_history — Past subscriptions
• purchase_credits — Buy a credit package (returns checkout URL)
• get_payment_history — Payment transaction history
• get_transaction_history — Credit ledger (purchases, consumption, refunds)
• get_usage_analytics — Submission counts, credit usage, daily breakdown
• get_consumption_breakdown — Credit usage by API endpoint

Development

npm install
npm run build
npm test
npm run dev  # run with tsx (hot reload)

Architecture

src/
├── index.ts               # MCP server entry point (stdio transport)
├── client/
│   ├── http-client.ts     # HTTP client with auth, retry, rate limiting
│   ├── invoice-client.ts  # Invoice service API client
│   └── billing-client.ts  # Billing service API client
├── tools/
│   ├── invoice-tools.ts   # 15 invoice tool definitions + handlers
│   ├── seller-tools.ts    # 7 seller tool definitions + handlers
│   ├── buyer-tools.ts     # 7 buyer tool definitions + handlers
│   └── billing-tools.ts   # 12 billing tool definitions + handlers
├── types/
│   ├── invoice.ts         # Invoice/seller/buyer types
│   └── billing.ts         # Billing/subscription/payment types
└── utils/
    └── format.ts          # Response formatting utilities

Versioning

This project follows Semantic Versioning with Conventional Commits.

npm run release         # auto-bump based on commits
npm run release:patch   # 0.1.0 → 0.1.1
npm run release:minor   # 0.1.0 → 0.2.0
npm run release:major   # 0.1.0 → 1.0.0

Contributing

See CONTRIBUTING.md for commit conventions, branching strategy, and how to add new tools.

License

MIT