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

• Install / use

• How the calculator works

  • Expression grammar

  • Angle mode and suffixes

  • Engineering symbols

  • Complex and polar

  • Evaluate pipeline

• Calculator modes → MCP tools

• MCP request and response conventions

• Tools reference

• Operator / function reference

• Constants reference

• Unit conversions

• Precision

• Limitations and safety

• Manual coverage gaps

• Possible future enhancements

• Tests

Related MCP server: sci-calc-mcp

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 --> jsonOut

Every 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 (evaluate and tools that take f(x)), or

• runs 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 called out 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

Precedence (tightest last): + - → * / % → unary - and ∠ → ^ → postfix !. ^ is right-associative.

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:

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 by 1000^n (ENG / ENG← style).

• Tools: eng_format, eng_shift.

• evaluate(..., eng_symbols=true) adds an eng object (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

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
  end

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.

evaluate

The primary tool for checking arithmetic and scientific expressions. Pass ordinary infix maths (parentheses, precedence, functions, constants). The server converts to RPN internally and returns the numeric result plus the internal rpn form for transparency. See Evaluate pipeline for the parse/eval flow.

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[] with name, arity, description, angle_sensitive

• list_constants → constants[] with name, value, unit, note, codata_year, optional catalog_index

• list_unit_conversions → conversions[] with id, from, to, plus factor or note for 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.

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).

{"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.

{"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 matrix n×(n+1), each row [a_i1, …, a_in, b_i], or

• A (n×n) and b (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.

{"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.

{"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.

{"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.

{"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": "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):

{"value": 12345}

{"ok": true, "value": 12345.0, "significand": 12.345, "exponent": 3, "symbol": "k", "display": "12.345k"}

product / factorize / fmin / fmax

• product — Π of infix f(x) from integer start to end (same shape as summation).

• factorize — prime factorization of a positive integer (n).

• fmin / fmax — approximate min/max of infix f(x) on [lower, upper] with angle_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 of N, I, PV, PMT, FV given 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

Exponentials and logarithms

Circular trigonometry (angle mode)

Hyperbolic (ignore angle mode)

Angle conversion helpers

Rounding and integers

Random

Complex

Engineering

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 (or echarge). Token e is Euler’s number.

• Classical electron radius is r_e. Token re is the real-part operator.

• Case-insensitive lookup is disabled for ambiguous pairs that collide when lowercased (e.g. muN vs mun). Prefer the exact spelling from this table or list_constants.

Unit conversions

Linear conversions multiply by a fixed factor. Temperature (C/F/K) uses affine conversion via kelvin.

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.

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

Scope boundaries

• Agents write infix; RPN is an internal implementation detail (also returned as rpn on evaluate for transparency).

• Not a CAS: no symbolic simplify, expand, or algebraic rearrange.

• Not arbitrary precision.

• Hyperbolic functions ignore angle_mode.

• Mid-expression RAD/DEG/GRAD tokens are not supported in infix — use the angle_mode parameter. Mid-expression ° / r / g (and deg/rad/grad) are supported and convert into the current angle mode.

• Glued engineering suffix: 2m means milli (0.002). For a binding named m, write 2*m.

• BASE-N does not accept leading -; use 32-bit patterns for negatives, or base_arith op neg. 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

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:

Medium gaps: richer % key patterns, sexagesimal arithmetic in expressions, fuller metric catalog, inequality compound-string form, named MatA–D session.

Possible future enhancements

Tests

pip install -e ".[dev]"
pytest --cov=mcp_calculator --cov-report=term-missing