invompt-mcp

MCP server for Invompt's public invoice API.

It exposes:

• invompt://spec/iml/v1 as a cached MCP resource

• create_invoice as the write tool for invoice creation

• draft_invoice_iml as an optional prompt for generating raw IML YAML

Quickstart

NPX

{
  "mcpServers": {
    "invompt": {
      "command": "npx",
      "args": ["-y", "invompt-mcp"],
      "env": {
        "INVOMPT_API_KEY": "inv_sk_your_key_here"
      }
    }
  }
}

Bunx

{
  "mcpServers": {
    "invompt": {
      "command": "bunx",
      "args": ["invompt-mcp"],
      "env": {
        "INVOMPT_API_KEY": "inv_sk_your_key_here"
      }
    }
  }
}

Requirements

• Node.js 18+

• An Invompt API key for create_invoice

The resource works without INVOMPT_API_KEY. The tool requires it when called.

Environment variables

INVOMPT_API_KEY

Required for:

• create_invoice

Not required for:

• invompt://spec/iml/v1

• draft_invoice_iml if you only want draft YAML and do not call the tool

INVOMPT_API_URL

Optional override for the API base URL.

Default:

https://invompt.com

Use this when targeting local, staging, or preview backends.

How it works

Resource: invompt://spec/iml/v1

• Reads GET /api/v1/spec/iml

• Returns plain text

• Uses a shared 1-hour in-memory cache

• Does not require authentication

Tool: create_invoice

Input:

{
  "iml": "meta:\n  invoice_number: INV-001\n  issue_date: 2026-03-21\n  currency: USD\nitems:\n  - desc: Design work\n    qty: 8\n    rate: 125\n",
  "templateId": "professional"
}

Supported templateId values:

• professional

• minimal

• modern

Success result:

{
  "invoiceId": "uuid-here",
  "url": "https://invompt.com/invoice/uuid-here"
}

On failure, the tool returns an MCP error result with a JSON body containing:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Prompt: draft_invoice_iml

• Fetches the same IML spec used by the resource

• Injects it into prompt context

• Instructs the model to return only raw IML YAML

Local development

Install dependencies:

npm install

Build:

npm run build

Run the server directly:

node dist/index.js

Run from source during development:

npm run dev

Local package-manager verification

For unpublished local verification, register the package with both package managers:

npm link
bun link

Then verify the server through an MCP client using:

npx invompt-mcp

and:

bunx invompt-mcp

Verification

Verified locally:

• npm run build

• npm test

• direct stdio startup via node dist/index.js

• npx invompt-mcp after npm link

• bunx invompt-mcp after bun link

Current verification scope:

• local MCP behavior is verified against a mock Invompt API

• live API verification still depends on deployed WS1 routes and migration state

Publish

The package includes a GitHub Actions workflow at .github/workflows/publish.yml.

It runs:

• npm ci

• npm run build

• npm test

• npm publish --provenance --access public

License

MIT