mcp_calculator
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp_calculator What is 90+(40-30)?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp_calculator
stdio MCP server that gives LLMs a scientific calculator with normal infix maths (e.g. 90+(40-30), sin(30), x^2-2). Expressions are parsed safely, converted internally to Reverse Polish Notation, and evaluated by a stack machine over allowlisted operators and constants — no Python eval/exec — so agents can verify numeric work without inventing answers.
Runtime: Python ≥3.10, dependency mcp≥1.0. Numerics use IEEE-754 float / complex via the standard math and cmath libraries (no SymPy, NumPy, or mpmath).
Table of contents
Related MCP server: mcp-calculator
Install / use (Cursor / Claude Desktop)
From GitHub:
{
"mcpServers": {
"mcp_calculator": {
"command": "uvx",
"args": ["--from", "git+https://github.com/mAd-DaWg/mcp_calculator", "mcp-calculator"]
}
}
}Local clone:
pip install -e ".[dev]"{
"mcpServers": {
"mcp_calculator": {
"command": "python",
"args": ["-m", "mcp_calculator"],
"cwd": "/path/to/mcp_calculator"
}
}
}Entry points: console script mcp-calculator, or python -m mcp_calculator. Transport is stdio only (no HTTP port or env-based precision flags).
How the calculator works
flowchart LR
client[MCP_client_stdio] --> tool[Tool_handler]
tool --> catch[catch_calc]
catch --> infix[Infix_lexer_shunting_yard]
catch --> domain[Domain_tools]
infix --> rpn[RPN_stack_engine]
domain --> jsonOut[JSON_string_response]
rpn --> jsonOutEvery tool goes through an error wrapper (catch_calc): failures come back as JSON with ok: false, never as a crashed process. From there, a call either:
parses an infix expression (
evaluateand tools that takef(x)), orruns a dedicated handler (matrix, stats, solve, BASE-N, distribution, LIST, finance, units, …).
Mode choices (angle unit, regression model, distribution type, which TVM unknown to solve, …) are tool parameters. Some limits are fixed (for example Base-N is always 32-bit) and are listed in the tool descriptions.
This server aims to cover ordinary scientific-calculator maths and common extras (stats, matrices, finance, …). Interactive calculator UI (screen formatting, graphing viewport, onboard programming IDE) is out of scope.
Expression grammar
Construct | Example |
Arithmetic |
|
Powers |
|
Unary minus |
|
Functions |
|
Multi-arg |
|
Factorial |
|
Constants |
|
Bindings |
|
Variable | calculus / roots / Σ / Π / table |
Implicit |
|
Precedence (PEMDAS / BODMAS / BIDMAS, tightest last): + - → * / % → ∠ → unary - → ^ → postfix !. Same level is left-to-right except ^, which is right-associative (2^3^2 = 2^(3^2) = 512). Parentheses first. This table is used by every infix tool (evaluate, calculus, roots, Σ/Π/table, list seq).
Angle mode and suffixes
Pass angle_mode on the tool (rad | deg | grad). It affects circular trig (sin, cos, tan, inverses, sec/csc/cot, atan2, arg). Hyperbolic functions ignore angle mode.
Mid-expression angle suffixes convert a literal into the current angle_mode before evaluation:
Suffix | Meaning |
| value is in degrees |
| value is in radians |
| value is in gradians |
flowchart LR
raw["literal_30_deg"] --> conv[Convert_into_angle_mode]
mode[angle_mode_param] --> conv
conv --> trig[sin_cos_tan_etc]Example: sin(30°) with angle_mode=rad converts 30° → π/6, then takes sine → ~0.5. Mid-expression RAD/DEG/GRAD tokens are not supported — use the tool parameter.
Engineering symbols
Glued SI prefixes after a real literal (engineering symbols):
f p n u/μ m k M G T P E
Examples: 500k → 500000, 3μ → 3e-6, 999k+25k → 1024000.
Infix:
engshift(x, n)multiplies by1000^n(ENG / ENG← style).Tools:
eng_format,eng_shift.evaluate(..., eng_symbols=true)adds anengobject (significand,exponent,symbol,display) for real results.
Note: glued 2m is milli (0.002). For a binding named m, write 2*m or 2 m.
Complex and polar
Form | Example |
Rectangular pack |
|
Polar input literal |
|
Polar function |
|
Output form |
|
Evaluate pipeline
flowchart TD
expr[expression_string] --> lex[Lex_numbers_names_ops]
lex --> suf[Apply_eng_and_angle_suffixes]
suf --> impl[Insert_implicit_multiply]
impl --> sy[Shunting_yard_to_RPN]
sy --> stack[Allowlisted_stack_eval]
stack --> fmt[Optional_complex_form_and_eng_display]
fmt --> resp[JSON_ok_result_rpn]Higher-level tools (matrix, stats, solve, BASE-N, units, …) use dedicated algorithms; differentiate, integrate, solve_root, Σ/Π/table evaluate infix in x.
Calculator modes → MCP tools
Modes map to tools; menu/editor choices are tool parameters. Defaults are overridable.
flowchart TB
subgraph calc [Calculate_Complex]
evaluate
calculus[differentiate_integrate]
end
subgraph stat [STAT_Distribution]
stats1[stats_1var]
stats2[stats_2var]
distr[distribution]
tests[stats_test]
end
subgraph other [Matrix_BaseN_Solve_List_Finance]
matrix_op
base[base_convert_arith]
solve[solve_tools]
list_op
finance_tvm
endCalculator mode | MCP tool(s) | Enterable / selectable inputs |
Calculate |
| expression; |
Complex |
|
|
Base-N |
| value/a/b, bases 2/8/10/16, op incl. |
Matrix / Vector |
|
|
Statistics |
| data; |
Distribution |
|
|
Table |
| f, optional g, start, end, step |
Equation / Func |
| coeffs / expression; |
Inequality |
| coefficients, |
Ratio |
| a,b,c,d + |
Spreadsheet | — | Possible future enhancement; use |
LIST |
|
|
Finance TVM |
|
|
STAT TESTS |
| z/t/prop/anova/linreg_ttest + editor fields |
Setup | per-call params | Defaults overridable; Pol/Rec default |
stats_2var model: linear, quadratic, logarithmic, exp, abexp, power, inverse, cubic, quartic, logistic, medmed.
distribution type: normal_pd/cd, inverse_normal (+ tail), binomial_*, inverse_binomial, poisson_*, geometric_*, t_*, chi2_*, f_*, norm_p/norm_q/norm_r.
MCP request and response conventions
Every tool returns a JSON string. The MCP layer delivers that string as tool-result text. Agents should JSON.parse it.
Success shape
{"ok": true, "...": "tool-specific fields"}Failure shape
{
"ok": false,
"error": "<code>",
"message": "human-readable explanation",
"hint": "how to fix the call",
"example": "optional",
"did_you_mean": "optional"
}On ok: false, read message, hint, and when present example / did_you_mean before retrying — those fields say what to fix. Discovery tools (list_operations, list_constants, list_unit_conversions) help recover from unknown tokens. Agents see tool docstrings and server instructions (When/Params/Example), not this README.
Illustrative MCP tools/call envelope
Clients send JSON-RPC over stdio. Example call for evaluate:
Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "evaluate",
"arguments": {
"expression": "90+(40-30)",
"angle_mode": "rad"
}
}
}Decoded tool payload (the string inside the tool result content):
{
"ok": true,
"result": 100.0,
"expression": "90+(40-30)",
"angle_mode": "rad",
"rpn": "90 40 30 - +"
}Below, examples show the arguments object and the parsed JSON response — what agents reason over after the MCP wrapper.
Tools reference
When this server is connected over MCP, the model sees each tool’s description (from the Python docstrings in server.py) plus the server instructions — not this README. Keep those in sync when changing behaviour.
Tool | Purpose |
| Main calculator: infix; eng/ |
| Discover available operators and function names |
| Discover math/physics constant names and values |
| Discover supported unit conversion ids |
| Matrix and vector algebra (det, inv, ref, rref, unit, eigen, …) |
| 1-VAR stats (+ optional FREQ; optional |
| Two-variable stats and selectable regression models |
| Solve a system of linear equations |
| Find a numeric root of f(x) = 0 |
| Find roots of a polynomial (degree 1–4) |
| Solve polynomial inequality with relation |
| Solve a:b = c:d for one unknown |
| Convert integers between binary/octal/decimal/hex (32-bit) |
| Integer arithmetic and bitwise ops in a chosen base |
| Approximate the derivative of f(x) at a point |
| Approximate a definite integral of f(x) |
| Σ of f(x) from start to end |
| Π of f(x) from start to end |
| Prime factorization (integer FACT) |
| Approximate min/max of f(x) on an interval |
| Rectangular ↔ polar coordinates |
| Sexagesimal ° ′ ″ conversion |
| Engineering display / ×1000ⁿ shift |
| Normal / binomial / Poisson / geometric / t / χ² / F (+ |
| STAT TESTS (z/t/prop/ANOVA/LinRegTTest) |
| LIST seq / cumsum / sort / ΔList |
| TVM solver (N, I%, PV, PMT, FV) |
| Generate f(x) [and g(x)] values by start/end/step |
| Convert a value between listed measurement units |
evaluate
The primary tool for checking arithmetic and scientific expressions. Pass ordinary infix maths (parentheses, PEMDAS / BODMAS / BIDMAS precedence, functions, constants). The server converts to RPN internally and returns the numeric result plus the internal rpn form for transparency. See Expression grammar and Evaluate pipeline.
Parameter | Type | Default | Description |
| string | required | Infix expression |
| string |
|
|
| string |
|
|
| object | optional | Name→float bindings (e.g. |
| bool |
| If true, real results include an |
Arguments
{"expression": "90+(40-30)", "angle_mode": "rad"}Response
{
"ok": true,
"result": 100.0,
"expression": "90+(40-30)",
"angle_mode": "rad",
"rpn": "90 40 30 - +"
}Degrees / grads
{"expression": "sin(30)", "angle_mode": "deg"}{
"ok": true,
"result": 0.49999999999999994,
"expression": "sin(30)",
"angle_mode": "deg",
"rpn": "30 sin"
}(sin(50) with angle_mode=grad likewise yields ~0.5.)
Angle suffix (convert into current angle_mode):
{"expression": "sin(30°)", "angle_mode": "rad"}Engineering suffixes
{"expression": "500k+10M"}{"ok": true, "result": 10500000.0, "expression": "500k+10M", "angle_mode": "rad", "rpn": "500000 10000000 +", "complex_form": "rectangular"}With eng_symbols: true, a real result also includes "eng": {"significand": 10.5, "exponent": 6, "symbol": "M", "display": "10.5M"}.
Polar complex input
{"expression": "2∠90", "angle_mode": "deg", "complex_form": "rectangular"}{"ok": true, "result": {"re": 1.2246467991473532e-16, "im": 2.0}, "expression": "2∠90", "angle_mode": "deg", "rpn": "2 90 polar", "complex_form": "rectangular"}Variables
{"expression": "A+B", "variables": {"A": 2, "B": 3}}Complex
{"expression": "abs(cmplx(3,4))"}{
"ok": true,
"result": 5.0,
"expression": "abs(cmplx(3,4))",
"angle_mode": "rad",
"rpn": "3 4 cmplx abs"
}A non-real complex result looks like "result": {"re": 1.0, "im": 2.0}. With complex_form": "polar" the same value is "result": {"r": …, "theta": …, "unit": …}.
Constants
{"expression": "sin(pi/6)"}{
"ok": true,
"result": 0.49999999999999994,
"expression": "sin(pi/6)",
"angle_mode": "rad",
"rpn": "pi 6 / sin"
}Error example
{"expression": "foo"}{
"ok": false,
"error": "unknown_token",
"message": "Unknown name 'foo' at position 0",
"hint": "Use a constant (list_constants), variable x, or function call like sin(x).",
"example": "pi/2",
"did_you_mean": "F",
"token": "foo",
"position": 0
}list_operations / list_constants / list_unit_conversions
Discovery helpers so agents do not guess names. Call these when unsure which operators, physics constants, or unit conversions exist. Each takes no parameters and returns ok: true plus an array:
list_operations→operations[]withname,arity,description,angle_sensitivelist_constants→constants[]withname,value,unit,note,codata_year, optionalcatalog_indexlist_unit_conversions→conversions[]withid,from,to, plusfactorornotefor temperature
See the operator, constants, and units catalogs below for the full inventories.
matrix_op
Linear algebra on small dense matrices and vectors: add/subtract/multiply, transpose, determinant, inverse, REF and RREF (distinct), identity, eigen, and vector ops (dot, 3D cross, Euclidean norm, angle, unit vector). Maximum dimension is 32.
Parameter | Type | Description |
| string |
|
| list | One or two matrices, or two vectors for vector ops |
| list of float | Single vector (e.g. for |
| int | Size for |
| string |
|
Determinant
{"op": "det", "matrices": [[[1, 2], [3, 4]]]}{"ok": true, "op": "det", "result": -2.0}Vector norm
{"op": "norm", "vector": [3, 4]}{"ok": true, "op": "norm", "result": 5.0}Angle (radians; includes "unit": "rad")
{"op": "angle", "matrices": [[1, 0], [0, 1]]}{"ok": true, "op": "angle", "result": 1.5707963267948966, "unit": "rad"}Cross product (requires 3-vectors)
{"op": "cross", "matrices": [[1, 0, 0], [0, 1, 0]]}{"ok": true, "op": "cross", "result": [0.0, 0.0, 1.0]}Identity (requires n)
{"op": "identity", "n": 2}{"ok": true, "op": "identity", "result": [[1.0, 0.0], [0.0, 1.0]]}stats_1var
One-variable descriptive statistics: count, mean, sum, sum of squares, min/max, Q1/median/Q3, mode, and population/sample variance and standard deviation (max 100 000 points).
Parameter | Type | Description |
| list of float | Non-empty |
| list of float | Optional FREQ column (same length as |
| float | Optional STAT Norm Dist input → adds |
{"data": [1, 2, 3, 4]}{
"ok": true,
"n": 4,
"mean": 2.5,
"sum": 10.0,
"sumsq": 30.0,
"min": 1.0,
"max": 4.0,
"median": 2.5,
"var_pop": 1.25,
"var_sample": 1.6666666666666667,
"std_pop": 1.118033988749895,
"std_sample": 1.2909944487358056
}STAT Norm Dist (norm_x)
When norm_x is set, the tool standardizes against the sample mean and population σ, then returns areas P/Q/R:
flowchart TD
data[data_and_optional_freq] --> stats[mean_and_sigma_pop]
x[norm_x] --> tcalc["t_equals_x_minus_mean_over_sigma"]
stats --> tcalc
tcalc --> P["P_area_neg_inf_to_t"]
tcalc --> Q["Q_area_0_to_t"]
tcalc --> R["R_area_t_to_pos_inf"]{"data": [1, 2, 3, 4, 5], "norm_x": 4}{
"ok": true,
"n": 5.0,
"mean": 3.0,
"std_pop": 1.4142135623730951,
"norm_x": 4.0,
"t": 0.7071067811865475,
"P": 0.7602499389065233,
"Q": 0.26024993890652326,
"R": 0.23975006109347674
}(Response also includes the usual 1-VAR fields: sum, sumsq, quartiles, variance, etc.)
stats_2var
Two-variable statistics and regression. Select Type is a required choice via model (not hardcoded to linear). Optional FREQ and ŷ/x̂ estimates match STAT Reg.
Parameter | Type | Default |
| list of float | required, equal length |
| string |
|
| list of float | optional |
| float | optional → |
| float | optional → |
{"x": [1, 2, 3], "y": [2, 4, 6], "model": "linear"}{
"ok": true,
"n": 3,
"model": "linear",
"a": 0.0,
"b": 2.0,
"r": 1.0,
"mean_x": 2.0,
"mean_y": 4.0,
"predict_at_mean": 4.0,
"equation": "y = a + b*x"
}{"x": [1, 2, 3, 4], "y": [1, 4, 9, 16], "model": "quadratic", "predict_y_at": 2}solve_linear
Solves a square system of linear equations Ax = b (unique solution when A is invertible). Pass either an augmented matrix or separate coefficient matrix A and right-hand side b. Uses Gaussian elimination with partial pivoting. Maximum size n = 32.
Pass either:
coefficients— augmented matrixn×(n+1), each row[a_i1, …, a_in, b_i], orA(n×n) andb(length n)
{"A": [[2, 1], [1, 3]], "b": [1, 2]}{
"ok": true,
"solution": [0.2, 0.6],
"residual": [0.0, -2.220446049250313e-16],
"status": "unique"
}solve_root
Finds a real number x where an infix expression f(x) equals zero (for example √2 from x^2-2). Prefer a bracketing interval [a, b] (Brent’s method); if you only have a starting guess, Newton’s method is used instead.
Parameter | Type | Default |
| string | required — infix in |
|
| preferred |
| float | for Newton |
| string |
|
{"expression": "x^2-2", "bracket": [0, 2]}{
"ok": true,
"root": 1.414213562373095,
"abs_f": 4.440892098500626e-16,
"iterations": 19,
"method": "brent",
"expression": "x^2-2",
"angle_mode": "rad"
}solve_polynomial
Finds roots of a₀ + a₁x + … + aₙxⁿ. Pass [a0, …, an] (constant first). Degree 1–4. allow_complex mirrors complex-solutions On/Off (default true).
{"coefficients": [-2, 0, 1], "allow_complex": true}{
"ok": true,
"degree": 2,
"roots": [1.4142135623730951, -1.4142135623730951],
"coefficients": [-2.0, 0.0, 1.0],
"allow_complex": true
}solve_inequality
Inequality mode: polynomial with relation >, >=, <, or <= (degree 1–4). Coefficients low-to-high like the Coefficient Editor.
{"coefficients": [-1, 1], "relation": ">"}solve_ratio
Ratio mode a:b = c:d. Provide three known values; solve_for is a|b|c|d|x (x = the single missing slot).
{"a": 2, "b": 3, "d": 6, "solve_for": "c"}{"ok": true, "a": 2.0, "b": 3.0, "c": 4.0, "d": 6.0, "solve_for": "c", "value": 4.0}base_convert
Converts an integer string from one base to another among 2, 8, 10, and 16, using 32-bit two’s complement (fixed — not a selectable bit width). Pass unsigned-style digit patterns for negatives (e.g. FFFFFFFF for −1).
{"value": "FF", "from_base": 16, "to_base": 10}{
"ok": true,
"value": "255",
"decimal": 255,
"decimal_unsigned": 255,
"from_base": 16,
"to_base": 10,
"bits": 32
}base_arith
Performs integer arithmetic and bitwise operations on values written in a chosen base (2/8/10/16), still in 32-bit two’s complement. Supports add, sub, mul, div, and, or, xor, xnor, unary not, and unary neg. Results wrap at 32 bits; div uses signed interpretation.
Parameter | Type | Default |
| string |
|
| string | required |
| string | required except for |
| int |
|
{"op": "add", "a": "A", "b": "5", "base": 16}{"ok": true, "op": "add", "result": "F", "decimal_unsigned": 15, "base": 16}differentiate
Approximates the derivative df/dx of an infix function of x at a given point, using a central finite difference. Use for checking calculus results numerically (not symbolic differentiation). Optional h overrides the automatic step size; truncation_est is a rough error hint.
Parameter | Type | Default |
| string | required — infix in |
| float | required — point of evaluation |
| string |
|
| float | auto: `(1+ |
{"expression": "x^3", "at": 2}{
"ok": true,
"derivative": 12.000000000147326,
"at": 2.0,
"h": 1.3924766500838347e-05,
"truncation_est": 3.8779838599604476e-10,
"expression": "x^3",
"angle_mode": "rad"
}integrate
Approximates the definite integral of an infix function of x from lower to upper using adaptive Simpson quadrature. Use to check ∫f(x) dx numerically. Optional tol tightens or loosens the accuracy target; the response includes error_est and how many times f was evaluated.
Parameter | Type | Default |
| string | required — infix in |
| float | required — integration limits |
| string |
|
| float |
|
{"expression": "x^2", "lower": 0, "upper": 1}{
"ok": true,
"integral": 0.3333333333333333,
"lower": 0.0,
"upper": 1.0,
"error_est": 0.0,
"evaluations": 5,
"expression": "x^2",
"angle_mode": "rad"
}Caps: recursion depth 40, ≤ 100 000 function evaluations.
summation
Σ: sum an infix expression in x for integer index from start to end inclusive.
{"expression": "x+1", "start": 1, "end": 5}{"ok": true, "sum": 20.0, "expression": "x+1", "index": "x", "start": 1, "end": 5, "angle_mode": "rad"}pol / rec
Rectangular ↔ polar. Default angle_mode is "deg".
{"x": 2, "y": 2, "angle_mode": "deg"}{"ok": true, "r": 2.8284271247461903, "theta": 45.0, "x": 2.0, "y": 2.0, "angle_mode": "deg"}dms_to_decimal / decimal_to_dms
Sexagesimal ° ′ ″ ↔ decimal degrees.
{"degrees": 10, "minutes": 30, "seconds": 0}{"ok": true, "decimal": 10.5, "degrees": 10.0, "minutes": 30.0, "seconds": 0.0}distribution
Distribution mode — pass type and every variable that type needs (none are hardcoded).
type | Required inputs |
|
|
|
|
|
|
|
|
|
|
|
|
| see tool docstring / |
|
|
{"type": "normal_pd", "x": 36, "sigma": 2, "mu": 35}{"type": "norm_p", "x": 1.0}eng_format / eng_shift
Engineering display helpers (also available in infix via suffixes and engshift):
Tool | Inputs | Result |
|
| significand / exponent / SI symbol / |
|
|
|
{"value": 12345}{"ok": true, "value": 12345.0, "significand": 12.345, "exponent": 3, "symbol": "k", "display": "12.345k"}product / factorize / fmin / fmax
product— Π of infixf(x)from integerstarttoend(same shape assummation).factorize— prime factorization of a positive integer (n).fmin/fmax— approximate min/max of infixf(x)on[lower, upper]withangle_mode.
stats_test / list_op / finance_tvm
stats_test— STAT TESTS: z/t/prop/ANOVA/LinRegTTest; pass the editor fields for the chosen test type.list_op— LIST:seq,cumsum,sort_a,sort_d,delta.finance_tvm— solve for one ofN,I,PV,PMT,FVgiven the other four.
table
Table mode: evaluate expression (and optional expression2 as g) from start to end by step.
{"expression": "2*x", "start": 0, "end": 2, "step": 1, "expression2": "x^2"}convert_unit
Converts a numeric value between common measurement units (length, area, volume, mass, pressure, force, energy, power, and temperature). Only pairs listed by list_unit_conversions are supported — there is no free-form dimensional analysis. Pass either a conversion_id or from_unit + to_unit. Full id list: Unit conversions.
{"value": 1, "conversion_id": "mile_to_km"}{
"ok": true,
"value": 1.609344,
"from_unit": "mile",
"to_unit": "km",
"conversion_id": "mile_to_km"
}Temperature example (100 °C → °F):
{"value": 100, "conversion_id": "C_to_F"}{"ok": true, "value": 212.0, "from_unit": "C", "to_unit": "F", "conversion_id": "C_to_F"}Operator / function reference
76 operators/functions from the allowlist. In infix, use binary symbols (+, ^, ∠, …) or function-call form name(args) matching arity. angle_sensitive means circular-trig / mode behavior. Call list_operations at runtime for the same data.
Arithmetic and powers
Name | Arity | Angle | Description |
| 2 | Addition | |
| 2 | Subtraction | |
| 2 | Multiplication | |
| 2 | Division | |
| 2 | Power | |
| 2 | Alias for | |
| 2 | Remainder (fmod); also | |
| 2 | Modulo | |
| 2 |
| |
| 1 | Negate (infix unary | |
| 1 | Absolute value / modulus — | |
| 1 | Reciprocal | |
| 1 | Square root — | |
| 1 | Cube root — | |
| 1 | Square — | |
| 1 | Cube — | |
| 2 |
| |
| 1 |
| |
| 2 | Minimum | |
| 2 | Maximum | |
| 2 | Hypotenuse | |
| 1 | Sign (−1, 0, 1) |
Exponentials and logarithms
Name | Arity | Description |
| 1 |
|
| 1 |
|
| 1 | Natural log |
| 1 | Log base 10 |
| 1 | Log base 2 |
| 2 |
|
Circular trigonometry (angle mode)
Name | Arity | Description |
| 1 | Forward trig |
| 1 | Inverse → angle mode |
| 2 |
|
| 1 | Reciprocal trig |
Hyperbolic (ignore angle mode)
Name | Arity | Description |
| 1 | Hyperbolic |
| 1 | Inverse hyperbolic |
| 1 | Reciprocal hyperbolic |
Angle conversion helpers
Name | Arity | Description |
| 1 | Degrees ↔ radians |
| 1 | Grads ↔ radians |
| 1 | Degrees ↔ grads |
Rounding and integers
Name | Arity | Description |
| 1 | Floor / ceiling / nearest |
| 1 | Truncate toward zero |
| 1 | Fractional part |
| 1 | Integer part (floor) |
| 1 | Factorial |
| 2 | Permutations / combinations — |
| 2 | GCD / LCM |
Random
Name | Arity | Description |
| 0 | Uniform float in |
| 2 | Random int inclusive — |
Complex
Name | Arity | Angle | Description |
| 2 | Pack re, im → complex — | |
| 2 | yes |
|
| 1 | Real / imaginary part — | |
| 1 | Conjugate — | |
| 1 | yes | Argument (angle mode) — |
Engineering
Name | Arity | Description |
| 2 |
|
Mode switches
RAD / DEG / GRAD exist in the internal op table (arity 0) but are not part of the infix grammar. Set angle_mode on the tool instead. Mid-expression angle suffixes (°/r/g) are supported — see Angle mode and suffixes.
Function/operator names are matched case-insensitively.
Constants reference
Physics values follow NIST CODATA 2022 (exact SI values where applicable). Use them as names in infix, e.g. c*qe.
Naming pitfalls
Elementary charge is
qe(orecharge). Tokeneis Euler’s number.Classical electron radius is
r_e. Tokenreis the real-part operator.Case-insensitive lookup is disabled for ambiguous pairs that collide when lowercased (e.g.
muNvsmun). Prefer the exact spelling from this table orlist_constants.
Token | Value | Unit | Note |
| 3.141592653589793 | 1 | Archimedes' constant |
| 2.718281828459045 | 1 | Euler's number |
| (alias of | 1 | Alias for |
| 6.283185307179586 | 1 |
|
| 1.618033988749895 | 1 | Golden ratio |
| +∞ | 1 | Positive infinity (ops that produce non-finite results still raise |
| 1.67262192595e-27 | kg | proton mass |
| 1.67492750056e-27 | kg | neutron mass |
| 9.1093837139e-31 | kg | electron mass |
| 1.883531627e-28 | kg | muon mass |
| 5.29177210544e-11 | m | Bohr radius |
| 6.62607015e-34 | J s | Planck constant (exact) |
| 5.0507837393e-27 | J T⁻¹ | nuclear magneton |
| 9.2740100657e-24 | J T⁻¹ | Bohr magneton |
| 1.0545718176461565e-34 | J s | reduced Planck constant |
| 7.2973525643e-3 | 1 | fine-structure constant |
| 2.8179403205e-15 | m | classical electron radius |
| 2.42631023538e-12 | m | Compton wavelength |
| 2.6752218708e8 | s⁻¹ T⁻¹ | proton gyromagnetic ratio |
| 1.32140985539e-15 | m | proton Compton wavelength |
| 1.31959090382e-15 | m | neutron Compton wavelength |
| 10973731.568157 | m⁻¹ | Rydberg constant |
| 1.66053906892e-27 | kg | atomic mass unit |
| 1.41060679545e-26 | J T⁻¹ | proton magnetic moment |
| −9.2847646917e-24 | J T⁻¹ | electron magnetic moment |
| −9.6623653e-27 | J T⁻¹ | neutron magnetic moment |
| −4.49044830e-26 | J T⁻¹ | muon magnetic moment |
| 96485.3321 | C mol⁻¹ | Faraday constant |
| 1.602176634e-19 | C | elementary charge (exact) |
| (alias of | C | Alias for |
| 6.02214076e23 | mol⁻¹ | Avogadro constant (exact) |
| 1.380649e-23 | J K⁻¹ | Boltzmann constant (exact) |
| (alias of | J K⁻¹ | Alias for |
| 0.02271095464 | m³ mol⁻¹ | molar volume ideal gas (273.15 K, 100 kPa) |
| 8.314462618 | J mol⁻¹ K⁻¹ | molar gas constant |
| 299792458 | m s⁻¹ | speed of light (exact) |
| 3.741771852e-16 | W m² | first radiation constant |
| 1.438776877e-2 | m K | second radiation constant |
| 5.670374419e-8 | W m⁻² K⁻⁴ | Stefan–Boltzmann constant |
| 8.8541878188e-12 | F m⁻¹ | vacuum permittivity |
| (alias of | F m⁻¹ | Alias for |
| 1.25663706127e-6 | N A⁻² | vacuum permeability |
| 2.067833848e-15 | Wb | magnetic flux quantum |
| 9.80665 | m s⁻² | standard gravity |
| 7.748091729e-5 | S | conductance quantum |
| 376.730313412 | ohm | vacuum impedance |
| 273.15 | K | 0 °C in kelvin |
| 6.67430e-11 | m³ kg⁻¹ s⁻² | Newtonian gravitation |
| 101325 | Pa | standard atmosphere |
Unit conversions
Linear conversions multiply by a fixed factor. Temperature (C/F/K) uses affine conversion via kelvin.
Id | From | To | Factor / note |
| in ↔ cm | 2.54 | |
| ft ↔ m | 0.3048 | |
| yd ↔ m | 0.9144 | |
| mile ↔ km | 1.609344 | |
| nmi ↔ m | 1852 | |
| pc ↔ km | 3.085677581e13 | |
| acre ↔ m2 | 4046.8564224 | |
| ha ↔ m2 | 10000 | |
| gal ↔ L | 3.785411784 | |
| floz ↔ mL | 29.5735295625 | |
| oz ↔ g | 28.349523125 | |
| lb ↔ kg | 0.45359237 | |
| atm ↔ Pa | 101325 | |
| mmHg ↔ Pa | 133.322387415 | |
| lbf ↔ N | 4.4482216152605 | |
| kgf ↔ N | 9.80665 | |
| cal ↔ J | 4.184 | |
| hp ↔ W | 745.6998715822702 | |
| C ↔ F | affine temperature | |
| C ↔ K | affine temperature | |
| F ↔ K | affine temperature |
There is no free-form dimensional analysis — only this table.
Precision
All numeric work uses IEEE-754 double (float) and Python complex. There is no arbitrary-precision mode and no Decimal/mpmath backend.
Mechanism | Threshold / default | Role |
Integer-ish check |
|
|
Imag → real | imag < | Treat as real in serialization / real-only ops |
Differentiate step |
| Default central-difference step |
Integrate |
| Adaptive Simpson tolerance (tool arg) |
Brent root |
| Bracketed root |
Newton root |
| Guess-based root |
Linear pivot | ~ | Singularity / no unique solution |
JSON |
| Non-finite values are not emitted; ops raise |
Practical accuracy: well-conditioned real arithmetic and trig typically agree with reference values to roughly 1e-9–1e-12 relative. Numerical differentiation, integration, and root-finding are weaker and depend on conditioning, step size, and tolerance — use the returned truncation_est, error_est, and abs_f fields as guidance, not guarantees.
Trig in degrees can show classic float artifacts (e.g. sin(30°) → 0.49999999999999994 rather than exact 0.5).
Limitations and safety
Hard limits
Limit | Value |
Expression length | 100 000 characters |
Token count | 10 000 |
Factorial | n ≤ 170 |
nPr / nCr | n ≤ 1000 |
Matrix / vector / linear system dimension | 32 |
Stats sample size | 100 000 |
Polynomial degree | 1–4 |
BASE-N | bases 2, 8, 10, 16 only; 32-bit two’s complement fixed (not selectable) |
Integration | depth ≤ 40; ≤ 100 000 evaluations |
Summation / table rows | ≤ 100 000 steps |
Calculus / root variable | only |
Calculus | numerical only (not symbolic) |
Units | fixed conversion table only |
Display Fix/Sci/Norm | not tool inputs — JSON returns full floats |
Scope boundaries
Agents write infix; RPN is an internal implementation detail (also returned as
rpnonevaluatefor transparency).Not a CAS: no symbolic simplify, expand, or algebraic rearrange.
Not arbitrary precision.
Hyperbolic functions ignore
angle_mode.Mid-expression
RAD/DEG/GRADtokens are not supported in infix — use theangle_modeparameter. Mid-expression°/r/g(anddeg/rad/grad) are supported and convert into the current angle mode.Glued engineering suffix:
2mmeans milli (0.002). For a binding namedm, write2*m.BASE-N does not accept leading
-; use 32-bit patterns for negatives, orbase_arithopneg. Bit width is not a parameter.Responses never include NaN/Inf JSON numbers; overflow becomes an error object.
Narrow UI/hardware exclusions: display Fix/Sci/Norm formatting, interactive graph viewport (Y=/TRACE), full calculator-Basic IDE. See gaps and future enhancements for numeric features not built yet.
Error codes
Code | Typical cause |
| Blank expression |
| Not |
| Bad name, character, function, or matrix/base op |
| Internal evaluation needed more operands |
| Internal evaluation left multiple values |
|
|
| Out-of-domain real/complex input |
| Non-finite result, size/bit/token limits |
| Integer domain violations |
| Bad syntax, arity, lists, missing args, bad |
| Matrix/system shape mismatch |
| Non-invertible matrix |
| Linear system under/over-determined |
| Root finder failed |
| Unsupported base or digits |
| Bad unit id/pair |
| Unexpected exception at tool boundary |
Safety
Expressions are lexed and dispatched through fixed operator and constant registries. There is no Python eval/exec of user input, and no subprocess invocation for calculation.
Manual coverage gaps
Common scientific calculator coverage is the minimum floor. Many former gaps are now implemented (Q1/Q3/mode, Σy…, factorize, Π, fMin/fMax, multi-var variables, Base-N neg, distribution extras, STAT TESTS, LIST, TVM, eigen, engineering symbols, polar ∠ literals, mid-expression °/r/g, STAT Norm Dist P/Q/R/t). Remaining:
Gap | Notes |
Spreadsheet | Deferred — see future list |
Math Box | Dice/coin/number line/unit circle pedagogy |
Medium gaps: richer % key patterns, sexagesimal arithmetic in expressions, fuller metric catalog, inequality compound-string form, named MatA–D session.
Possible future enhancements
Enhancement | Notes |
Spreadsheet mode | Grid + formulas; workaround via numeric tools today |
Math Box | Pedagogy / simulation |
Named MatA–D / MatAns session | Bindings and/or session |
Interactive graphing / calculator-Basic IDE | Narrow UI exclusions unless requested |
Plot data APIs | Without full viewport |
Tests
pip install -e ".[dev]"
pytest --cov=mcp_calculator --cov-report=term-missingAvailable Tools
33 toolsbase_arithA
When: integer/bitwise arithmetic in a chosen base (32-bit), not floating evaluate. Params: op=add|sub|mul|div|and|or|xor|xnor|not|neg; a; b (except not/neg); base=2|8|10|16. Example: op="add", a="A", b="5", base=16.
Inputs: a (required), op (required), b, base. Returns: result
base_convertA
When: convert an integer string between bases 2/8/10/16 (32-bit two's complement fixed). Params: value (digit string, no leading '-'; use FFFFFFFF-style for negatives); from_base, to_base in {2,8,10,16}. Example: value="FF", from_base=16, to_base=10.
Inputs: value (required), to_base (required), from_base (required). Returns: result
convert_unitA
When: convert between listed measurement units (not free-form dimensional analysis). Params: value; either conversion_id OR from_unit+to_unit. Call list_unit_conversions first if unsure. Example: value=1, conversion_id="mile_to_km".
Inputs: value (required), to_unit, from_unit, conversion_id. Returns: result
decimal_to_dmsB
When: decimal degrees → ° ′ ″ components. Params: decimal. Example: decimal=10.5 → degrees=10, minutes=30, seconds=0.
Inputs: decimal (required). Returns: result
differentiateA
When: numerical derivative df/dx of infix f(x) at a point (not symbolic). Params: expression in x; at; angle_mode; optional h step. Example: expression="x^3", at=2.
Inputs: at (required), expression (required), h, angle_mode. Returns: result
distributionA
When: probability densities/CDFs/inverses (DISTR), or norm_p/q/r for standardized t. For Norm Dist from a data list use stats_1var(norm_x=…) instead. Params: type selects screen — pass every variable that type needs. Types: normal_pd (x,sigma,mu), normal_cd (lower,upper,sigma,mu), inverse_normal (area,sigma,mu,tail), binomial_pd/cd (x,n,p), inverse_binomial, poisson_*, geometric_*, t_pd/cd, chi2_pd/cd, f_pd/cd, norm_p/q/r (x=t). Example: type="normal_pd", x=36, sigma=2, mu=35.
Inputs: type (required), n, p, x, +10 more. Returns: result
dms_to_decimalA
When: sexagesimal ° ′ ″ → decimal degrees. Params: degrees; optional minutes, seconds (default 0). Example: degrees=10, minutes=30, seconds=0 → 10.5.
Inputs: degrees (required), minutes, seconds. Returns: result
eng_formatA
When: show a real number in engineering form (significand + SI symbol). Prefer evaluate eng_symbols for expression results. Params: value. Example: value=12345 → display "12.345k".
Inputs: value (required). Returns: result
eng_shiftA
When: ENG / ENG← style shift: multiply by 1000^steps (also engshift(x,n) in evaluate). Params: value; steps (default 1; negative shifts down). Example: value=1234, steps=1 → 1.234e6-style shift.
Inputs: value (required), steps. Returns: result
evaluateA
When: ordinary infix maths (real/complex), trig, powers, eng suffixes, angle suffixes, polar ∠. Not for matrices, stats lists, BASE-N, TVM, or unit conversion tables. Params: expression (required); angle_mode=rad|deg|grad (default rad); complex_form=rectangular|polar; variables={name:float}; eng_symbols=bool. Example: expression="sin(30°)", angle_mode="rad"; or "500k+10M"; or "2∠90" with angle_mode="deg".
Inputs: expression (required), variables, angle_mode, eng_symbols, +1 more. Returns: result
factorizeA
When: prime factorization of a positive integer (not evaluate fact()). Params: n (positive integer, ≤10 digits). Example: n=12 → factors with multiplicity.
Inputs: n (required). Returns: result
finance_tvmA
When: time-value-of-money (loan/annuity) — solve one of N,I,PV,PMT,FV. Params: solve_for=N|I|PV|PMT|FV; provide the other four; I is annual %; P_Y payments/year (default 1); C_Y compounds/year (default=P_Y); begin=True for BGN. Signs: outflow negative / inflow positive, kept consistent. Example: solve_for="PMT", N=12, I=6, PV=-1000, FV=0.
Inputs: solve_for (required), I, N, FV, +5 more. Returns: result
fmaxA
When: approximate maximum of infix f(x) on a closed interval. Params: expression in x; lower; upper; angle_mode; tol. Example: expression="-(x-1)^2", lower=0, upper=2.
Inputs: lower (required), upper (required), expression (required), tol, +1 more. Returns: result
fminA
When: approximate minimum of infix f(x) on a closed interval. Params: expression in x; lower; upper; angle_mode; tol. Example: expression="(x-1)^2", lower=0, upper=2.
Inputs: lower (required), upper (required), expression (required), tol, +1 more. Returns: result
integrateA
When: numerical definite integral of infix f(x) on [lower, upper]. Params: expression in x; lower; upper; angle_mode; tol (default 1e-10). Example: expression="x^2", lower=0, upper=1.
Inputs: lower (required), upper (required), expression (required), tol, +1 more. Returns: result
list_constantsA
When: need CODATA/math constant names (pi, e, qe, …) usable in evaluate. Params: none. Example: call with no args → constants[{name,value,unit,…}].
Inputs: no named parameters. Returns: result
list_opA
When: LIST utilities (sequence, cumsum, sort, ΔList) — not stats summaries. Params: op=seq|cumsum|sort_a|sort_d|delta; seq needs expression,start,end[,step]; others need data; angle_mode for seq expressions. Example: op="cumsum", data=[1,2,3]; or op="seq", expression="2*x", start=1, end=3.
Inputs: op (required), end, data, step, +3 more. Returns: result
list_operationsA
When: unknown function/operator name after evaluate unknown_token, or exploring arity. Params: none. Example: call with no args → operations[{name,arity,description,angle_sensitive}].
Inputs: no named parameters. Returns: result
list_unit_conversionsA
When: before convert_unit, or unknown conversion_id / unit pair. Params: none. Example: call with no args → conversions[{id,from,to,…}].
Inputs: no named parameters. Returns: result
matrix_opA
When: matrix/vector algebra (not infix evaluate). Params: op=add|sub|mul|transpose|det|inv|identity|ref|rref|eigen|dot|cross|norm|angle|unit; matrices=[A] or [A,B]; vector=[…] for norm/unit; n for identity; angle_mode for angle. Example: op="det", matrices=[[[1,2],[3,4]]].
Inputs: op (required), n, vector, matrices, +1 more. Returns: result
polA
When: convert rectangular (x,y) to polar (r,θ). Prefer over manual atan2 for this mode. Params: x, y; angle_mode for θ (default deg). Example: x=2, y=2, angle_mode="deg" → r≈2.828, θ=45.
Inputs: x (required), y (required), angle_mode. Returns: result
productB
When: discrete product Π f(x) for integer x from start to end inclusive. Params: expression in x; start; end; angle_mode. Example: expression="x", start=1, end=4 → 24.
Inputs: end (required), start (required), expression (required), angle_mode. Returns: result
recA
When: convert polar (r,θ) to rectangular (x,y). Params: r, theta; angle_mode for θ (default deg). Example: r=2, theta=90, angle_mode="deg".
Inputs: r (required), theta (required), angle_mode. Returns: result
solve_inequalityA
When: solve polynomial inequality a0+…+an x^n (degree 1–4). Params: coefficients=[a0,...,an]; relation=">"|">="|"<"|"<=". Example: coefficients=[-1,1], relation=">" for x-1>0.
Inputs: relation (required), coefficients (required). Returns: result
solve_linearA
When: square linear system Ax=b (not polynomial roots or f(x)=0). Params: either A (n×n) and b (len n), or coefficients as augmented n×(n+1). Max n=32. Example: A=[[2,1],[1,3]], b=[1,2].
Inputs: A, b, coefficients. Returns: result
solve_polynomialA
When: roots of a polynomial a0+…+an x^n (degree 1–4), not general f(x). Params: coefficients=[a0,...,an]; allow_complex=bool (default true). Example: coefficients=[-2,0,1] for x^2-2=0.
Inputs: coefficients (required), allow_complex. Returns: result
solve_ratioA
When: proportion a:b = c:d with one unknown. Params: three of a,b,c,d known; solve_for=a|b|c|d|x (x = the single missing slot). Example: a=2, b=3, d=6, solve_for="c".
Inputs: a, b, c, d, +1 more. Returns: result
solve_rootA
When: numeric root of infix f(x)=0 (prefer over guessing). Params: expression in x; prefer bracket=[a,b]; else guess; angle_mode for trig in f. Example: expression="x^2-2", bracket=[0,2].
Inputs: expression (required), guess, bracket, angle_mode. Returns: result
stats_1varA
When: one-variable summary stats, or STAT Norm Dist t/P/Q/R from a data list. Params: data (required); optional freq (same length); optional norm_x → adds t,P,Q,R (t=(x−mean)/σ_pop; P:−∞→t, Q:0→t, R:t→+∞). Example: data=[1,2,3,4,5], norm_x=4.
Inputs: data (required), freq, norm_x. Returns: result
stats_2varA
When: paired (x,y) stats and regression — not single-list stats_1var. Params: x,y equal length; model=linear|quadratic|logarithmic|exp|abexp|power|inverse| cubic|quartic|logistic|medmed (default linear); optional freq, predict_y_at, predict_x_at. Example: x=[1,2,3], y=[2,4,6], model="linear".
Inputs: x (required), y (required), freq, model, +2 more. Returns: result
stats_testA
When: STAT hypothesis tests (not descriptive stats_1var / regression stats_2var). Params: type=z_test|t_test|2_samp_t_test|1_prop_z_test|2_prop_z_test|anova|linreg_ttest; pass editor fields for that type (data/sigma/mu0, x/n/p0, lists for ANOVA, …); alternative; pooled for two-sample. Example: type="t_test", data=[1,2,3], mu0=0.
Inputs: type (required), n, x, n1, +11 more. Returns: result
summationA
When: discrete sum Σ f(x) for integer x from start to end inclusive. Params: expression in x; start; end; angle_mode. Example: expression="x+1", start=1, end=5.
Inputs: end (required), start (required), expression (required), angle_mode. Returns: result
tableB
When: generate f(x) [and optional g(x)] values from start to end by step. Params: expression in x; start; end; step; optional expression2; angle_mode. Example: expression="2*x", start=0, end=2, step=1, expression2="x^2".
Inputs: end (required), step (required), start (required), expression (required), +2 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Each tool has a clearly distinct purpose, from basic evaluation to specific operations like matrix algebra, statistics, and unit conversion. Even similar tools like solve_polynomial and solve_root are explicitly differentiated, and helper tools like list_operations aid discovery without overlap.
Most tools follow a consistent snake_case verb_noun pattern (solve_*, list_*, convert_*), but a few abbreviations (pol, rec) and single-word names (table, product) introduce minor inconsistency.
With 33 tools, the count exceeds the recommended range for a well-scoped server. While each tool serves a distinct calculator function, the sheer number feels heavy and may burden an agent's selection process, per the 25+ threshold.
The tool set comprehensively covers calculator domains: arithmetic, algebra, calculus, statistics, probability, matrices, base-n, finance, and conversions. Helpers for listing operations and constants ensure discoverability, with no obvious missing capabilities for a scientific calculator.
Maintenance
Related MCP Connectors
Unofficial Math.js MCP — wraps the mathjs.org API (free, no auth)
Safe scientific calculator MCP for numeric expressions
This MCP server enables users to perform scientific computations regarding linear algebra and vect…
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseNot gradedqualityDmaintenancesci_calc_mcp is a lightweight, high-performance Model Context Protocol (MCP) server that exposes scientific calculator operations as atomic tools.MIT
- AlicenseAqualityCmaintenanceAn MCP server that integrates the MathJS library to provide AI models with advanced calculation capabilities, including support for complex numbers, matrices, and unit conversions. It supports both stdio and HTTP transports for seamless integration with clients like Claude Desktop and GitHub Copilot.161 npmMIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server providing 150+ mathematical functions across arithmetic, trigonometry, statistics, unit conversions, and more, consolidated into 15 powerful tools for seamless integration with VS Code Copilot and other MCP-compatible clients.MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol (MCP) server that provides basic mathematical, statistical and trigonometric functions to Large Language Models (LLMs).5933 npm1MIT