# Numeral MCP by usefulapi

> Numeral MCP by usefulapi is an MCP server. Calculate sales tax & VAT, record transactions and refunds, manage products and customers. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Website:** https://usefulapi.io/numeral/
- **Repository:** https://github.com/m190/usefulapi-mcp/tree/HEAD/servers/numeral
- **MCP Registry name:** io.usefulapi/numeral
- **Listing updated:** 2026-11-13

## About

Calculate sales tax & VAT, record transactions and refunds, manage products and customers.

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http numeral https://numeral.usefulapi.io/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://numeral.usefulapi.io/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "numeral": {
      "url": "https://numeral.usefulapi.io/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "numeral": {
      "type": "http",
      "url": "https://numeral.usefulapi.io/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "numeral": {
      "serverUrl": "https://numeral.usefulapi.io/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "numeral": {
      "type": "http",
      "url": "https://numeral.usefulapi.io/mcp"
    }
  }
}
```

## Tools

- `numeral_ping`: Health check — verifies the API key works and reports the environment (test/prod), api_version, and server timestamp. Numeral: GET /tax/ping.
- `numeral_calculate_tax`: Calculate sales tax / VAT for an order — a STATELESS quote that persists nothing (record it later with numeral_create_transaction using the returned calculation id). Returns per-jurisdiction rates, total_tax_amount, and totals. Provide a customer address and one or more line items (each needs reference_product_id OR product_category). Amounts are in the currency's smallest unit (cents). Numeral: P
- `numeral_get_transaction`: Get a recorded transaction by its Numeral id (tr_...). Returns the transaction with its line items, currencies, and metadata. Numeral: GET /tax/transactions/{transaction_id}.
- `numeral_list_transaction_refunds`: List all refunds recorded against a transaction. Returns {refunds:[...]}. Numeral: GET /tax/transactions/{transaction_id}/refunds.
- `numeral_list_products`: List your Numeral products (up to 50 per page), each with its reference id, name, and product_category. Use `cursor` (the last_product_id from a previous page) to paginate; has_more indicates more pages. Numeral: GET /tax/products.
- `numeral_get_product`: Get a single product by its reference_product_id (your id). Returns the product's name, product_category, and timestamps. Numeral: GET /tax/products/{reference_product_id}.
- `numeral_get_customer`: Get a customer by id. By default `customer_id` is the Numeral id (cus_...); set id_type to "reference" to look up by your own reference_customer_id. Returns name, email, and tax-exempt status. Numeral: GET /tax/customers/{customer_id}.
- `numeral_create_transaction`: RECORDS a completed sale as a transaction — this WRITES a live tax/compliance record used for filings. Supply the `calculation_id` returned by numeral_calculate_tax and your `reference_order_id`. Numeral: POST /tax/transactions.
- `numeral_create_refund`: RECORDS a refund against a transaction — this WRITES a live tax/compliance record (adjusts tax owed). Use type="full" to refund the whole transaction, or type="partial" with line_items (each keyed by reference_product_id) for a partial refund. Numeral: POST /tax/refunds.
- `numeral_create_product`: CREATES (or upserts) a product with its tax category — this WRITES to your Numeral product catalog, which drives future tax calculations. Numeral: POST /tax/products.
- `numeral_create_customer`: CREATES a customer record — this WRITES to your Numeral customer list (used for order tracking and tax exemptions). Numeral: POST /tax/customers.

## FAQ

### How do I add Numeral MCP by usefulapi to Claude Code?

Run this command in your terminal: claude mcp add --transport http numeral https://numeral.usefulapi.io/mcp

---
Source: https://ai-powered.com/mcp/numeral-mcp-by-usefulapi
