# Roman Numeral Converter

> Converts an integer from 1 to 3999 into standard (subtractive-notation) Roman numerals, or parses a Roman numeral back into a number, and shows the value of each symbol group.

- Calculator id: `roman-numeral` · Category: Everyday Life (`everyday`) · Tool name: `convert_roman_numeral`
- Canonical page: https://tttkmbb.com/everyday/roman-numeral · This document: https://tttkmbb.com/everyday/roman-numeral.md · JSON definition: https://tttkmbb.com/everyday/roman-numeral.json

## Purpose

Converts an integer from 1 to 3999 into standard (subtractive-notation) Roman numerals, or parses a Roman numeral back into a number, and shows the value of each symbol group.

**Use when:** You need to write a year, chapter or clock number in Roman numerals, or read one such as MCMXCIV.

**Do not use when:** The number is 0, negative, 4000 or larger, or not an integer (standard Roman numerals cannot express these); for other number systems use base-converter.

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `mode` | enum: to_roman \| from_roman |  | required | Conversion direction. |
| `value` | string |  | required | The integer (1–3999) for to_roman, or the Roman numeral (I, V, X, L, C, D, M; case-insensitive) for from_roman. |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `roman` | string |  | The numeral in standard form. |
| `number` | integer |  | The decimal value. |
| `breakdown` | string |  | Symbol groups with their values, e.g. M (1000) + CM (900) + XC (90) + IV (4). |

## Formula

`Greedy decomposition using M 1000, CM 900, D 500, CD 400, C 100, XC 90, L 50, XL 40, X 10, IX 9, V 5, IV 4, I 1; parsing accepts only the standard form M{0,3}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})`

## Data Sources

- Roman numerals (Wikipedia) — https://en.wikipedia.org/wiki/Roman_numerals (reference, retrieved 2026-09-23)

Data freshness: `static`. Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output.

## API

- `GET https://tttkmbb.com/api/v1/calculate/roman-numeral?mode=…&value=…`
- `POST https://tttkmbb.com/api/v1/calculate/roman-numeral` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/roman-numeral · OpenAPI operationId `convert_roman_numeral` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "roman-numeral", "inputs": {…}}`

## Example

- 1994 to Roman: inputs `{"mode":"to_roman","value":"1994"}` → `{"roman":"MCMXCIV","number":1994,"breakdown":"M (1000) + CM (900) + XC (90) + IV (4)"}`
- MMXXVI to number: inputs `{"mode":"from_roman","value":"MMXXVI"}` → `{"roman":"MMXXVI","number":2026,"breakdown":"M (1000) + M (1000) + X (10) + X (10) + V (5) + I (1)"}`

```
GET https://tttkmbb.com/api/v1/calculate/roman-numeral?mode=to_roman&value=1994
```

## Limitations

The number is 0, negative, 4000 or larger, or not an integer (standard Roman numerals cannot express these); for other number systems use base-converter. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**Why is IIII or VIIII rejected?**

The converter accepts only standard subtractive notation (IV, IX, XL, XC, CD, CM). Additive forms such as IIII on clock faces are historical variants and are not parsed.

**How are numbers above 3999 written?**

With a vinculum (overline) multiplying a group by 1000, e.g. an overlined IV for 4000. This calculator supports 1–3999 only.

## Related

- [Number Base Converter](https://tttkmbb.com/math/base-converter.md) — Convert between binary, octal, decimal and hexadecimal.