How do I use mcp-units?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-units convert 50 meters per second to miles per hour" 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-units

by quantumleeps

Overview Schema Related Servers Score Discussions

Python

Hybrid

mcp-units

An MCP server that provides deterministic unit conversions via Pint. LLMs guess at unit conversions — this server makes them exact.

What this does

Exposes 5 tools, 3 resources, and 2 prompts over the Model Context Protocol. Any MCP client (Claude Code, Claude Desktop, Cursor) can convert units, check dimensional compatibility, parse quantity strings, and simplify expressions — all backed by Pint's 400+ unit registry instead of LLM arithmetic.

Related MCP server: MCP Mathematics

How it works

A FastMCP server wraps Pint's UnitRegistry and exposes it through MCP primitives:

Tools — convert, check_compatibility, parse_quantity, list_compatible_units, simplify
Resources — units://systems, units://systems/{system}, units://dimensions
Prompts — convert_document (extract and convert all quantities in text), check_calculations (verify dimensional consistency)

The server runs over stdio by default (for Claude Code / Claude Desktop) or Streamable HTTP via fastmcp run (for remote / containerized deployment).

Quickstart

Prerequisites

Python 3.12+
uv

Install and run

git clone https://github.com/quantumleeps/mcp-units.git
cd mcp-units
uv sync

Add to Claude Code

claude mcp add --transport stdio mcp-units -- \
  uv run --directory /path/to/mcp-units mcp-units

Add to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-units": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-units", "mcp-units"]
    }
  }
}

Run over HTTP

uv run fastmcp run src/mcp_units/server.py --transport http --port 8000

Docker

docker build -t mcp-units .
docker run -p 8000:8000 mcp-units

Tests

uv sync --all-extras
uv run pytest

Evaluation

Does giving an LLM access to a unit conversion tool actually improve its accuracy on physics problems?

Tool impact across 6 Claude models

Evaluated on 70 SciBench college-level physics problems requiring 2+ unit types, across 6 Claude models (840 total runs). Opus 4.6 — the latest model — shows the largest gain (+8.6pp, 70.0% → 78.6%), suggesting that its combination of broad knowledge and refined tool-use lets it leverage unit conversion as a reliable augmentation. 4.5-Sonnet, a strong reasoner and tool user, also improves (+2.9pp). The older 3.7-Sonnet regresses (-2.9pp) — analysis shows it sometimes treats an intermediate conversion result as the final answer, or spins through repeated tool calls without converging, consistent with less mature tool-use capabilities. The surprise is 4.5-Haiku: same generation as 4.5-Sonnet with capable reasoning and tool use, yet it declines (-1.4pp). With a smaller model, the tool appears to be a distraction rather than an augmentation — the model has the sophistication to use it but not always the judgment to know when it helps. With only 70 problems and a single run per model, these per-model deltas carry real uncertainty — the 4.5-Haiku result in particular could reflect noise rather than a meaningful pattern.

Next steps

Unit normalization — Models write cm3 but Pint needs cm^3. A lightweight normalize_unit() preprocessor plus better tool descriptions with formatting guidance would eliminate the 12 parsing failures observed in the eval.
Expression evaluation — Models sometimes pass math expressions (-1.602e-19 * 1.33e-39 / ...) as the value parameter to convert(). Pint rejects these since it expects a float. Accepting and evaluating simple arithmetic expressions would let the tool handle intermediate calculations.
Offset unit handling — Pint raises OffsetUnitCalculusError for °C and °F in compound expressions. The parse_quantity tool needs special handling for temperature offsets.
Larger problem set — 70 problems demonstrates the evaluation framework but limits statistical confidence on per-model deltas. Run-to-run variance within a single model is also unknown. Expanding to 200+ problems with multiple runs per problem would quantify both effects.

Run the eval

uv sync --group eval
uv run python -m eval.runner          # run all 6 models × 2 conditions (requires ANTHROPIC_API_KEY)
uv run python -m eval.visualize       # generate charts from results
uv run python -m eval.analyze         # print detailed analysis

Project Structure

mcp-units/
  src/mcp_units/
    server.py       # FastMCP instance — tools, resources, prompts
    registry.py     # Pint UnitRegistry + compatible units workaround
    models.py       # Result dataclasses for structured tool output
  eval/
    runner.py       # Async eval runner — baseline vs tool-augmented
    problems.py     # SciBench problem loading (70 problems, 2+ unit types)
    scorer.py       # Answer extraction + 5% tolerance scoring
    mcp_tools.py    # FastMCP Client wrapper for tool execution
    results.py      # RunResult dataclass + JSON persistence
    visualize.py    # Grouped bar chart + error histograms
    analyze.py      # 16-section detailed analysis
  tests/
    test_tools.py   # 18 Pint logic tests
    test_server.py  # 17 MCP Client integration tests
  Dockerfile        # HTTP transport for containerized deployment

Contributing

PRs welcome. Run pre-commit install after cloning and ensure uv run pytest passes before submitting.

License

MIT

Available Tools

5 tools

check_compatibilityB

Check if two units are dimensionally compatible (i.e., can be converted).

Returns whether the units share the same physical dimension.

ParametersJSON Schema

Name	Required	Description	Default
`unit_a`	Yes
`unit_b`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`unit_a`	Yes
`unit_b`	Yes
`compatible`	Yes
`explanation`	Yes
`dimensionality_a`	Yes
`dimensionality_b`	Yes

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It adequately states that the tool returns a boolean indicating dimensional compatibility, implying it is read-only with no side effects. However, it does not explicitly mention that it does not modify data or require special permissions, leaving some ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at two sentences, with no superfluous words. It front-loads the core action ('Check if two units are dimensionally compatible') and adds a clarifying parenthetical and return value explanation. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description provides a basic understanding but lacks completeness. It does not specify the format of unit strings or mention the output schema (which likely indicates the boolean return). For a tool with siblings, more context on when to use it would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no descriptions for the two required parameters (unit_a, unit_b), and the description does not provide any additional meaning about them. It fails to explain that these are strings representing unit expressions, or what format is expected. With 0% schema coverage, the description offers no parameter-level guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool checks if two units are dimensionally compatible, with the elaboration that it checks if they can be converted. This is distinct from sibling tools like 'convert' (which performs conversion) and 'list_compatible_units' (which lists all compatible units), making the purpose highly specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus its siblings. For example, it does not suggest using this tool before calling 'convert' to verify compatibility, nor does it mention that 'list_compatible_units' could provide a list of compatible units. The description gives no context on appropriate usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convertA

Convert a value from one unit to another.

Returns the converted value with conversion factor, or a structured error if the units are dimensionally incompatible.

ParametersJSON Schema

Name	Required	Description	Default
`value`	Yes
`to_unit`	Yes
`from_unit`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description discloses return value shape (converted value, conversion factor, or structured error for incompatible units), which is helpful. No annotations are present, so the description carries the burden. It does not mention idempotency or side effects, but for a conversion tool, the behavior is well captured.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The key information (what it does, what it returns) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of unit conversions (multiple unit systems, compound units), the description is too sparse. Parameter details are missing, and there is no cross-reference to sibling tools that might help with unit discovery. The output schema may exist but is not available to evaluate; still, the description does not fully compensate for the lack of schema descriptions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 0% description coverage, so the description must compensate. However, the description does not explain what from_unit and to_unit expect (e.g., string format, allowed values). It only says 'unit' without details, leaving the agent guessing about accepted unit syntax.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb ('convert') and resource ('value from one unit to another'), and distinguishes from siblings like check_compatibility (which only checks) and list_compatible_units (which lists).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or not-to-use advice, but the tool's purpose is clear enough that it is the main conversion tool. Sibling tools are conceptually distinct, but no guidance is given on when to choose convert over check_compatibility or others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_compatible_unitsA

List all units compatible with the given unit.

Returns every canonical unit name that shares the same physical dimension, including imperial and US customary units.

ParametersJSON Schema

Name	Required	Description	Default
`unit`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It reveals that the tool returns all canonical unit names of the same physical dimension, including imperial and US customary units. It does not cover error handling or edge cases, but for a simple listing tool, this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two short, focused sentences. It is front-loaded with the purpose and provides all necessary information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, existence of output schema), the description adequately covers the tool's purpose, input, and output semantics. No additional information is needed for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'unit' has no schema description (0% coverage). The tool description adds meaning by stating it lists units compatible with the given unit, indicating the parameter is the unit to check. This adds value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all units compatible with a given unit, specifying it returns canonical unit names sharing the same physical dimension, including imperial and US customary. This is a specific verb+resource, and distinguishes from sibling tools like 'convert' or 'check_compatibility'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (to list all compatible units), but does not explicitly state when not to use it or provide direct comparisons to siblings. Given the context, an agent can infer usage, but explicit guidance would improve the score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

parse_quantityA

Parse a quantity string into structured components.

Accepts expressions like '100 mg/L' or '9.81 m/s²'. Returns the magnitude, units, dimensionality, and SI equivalent.

ParametersJSON Schema

Name	Required	Description	Default
`expression`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It discloses the return structure but does not mention error handling, edge cases, or any side effects. For a pure parsing function, the behavioral profile is partially covered, but there is room for more transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with the purpose stated first, followed by examples and return details. Every sentence adds value, and there is no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, output schema available), the description covers the core functionality and return values. It adds context about dimensionality and SI equivalent not in the schema. However, it lacks notes on error handling or input validation, but the output schema likely fills return structure gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, requiring the description to compensate. It provides examples ('100 mg/L', '9.81 m/s²') which add practical meaning, but does not formally define the expected format, constraints, or allowed syntax for the expression parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool parses a quantity string into structured components, with examples and a list of returned fields (magnitude, units, dimensionality, SI equivalent). This is a specific verb+resource and distinguishes from sibling tools like convert or check_compatibility.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you need to parse a quantity string but provides no explicit guidance on when to use this tool versus alternatives (e.g., convert, list_compatible_units). No when-not-to-use or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

simplifyA

Simplify a unit expression to its most compact form.

Adjusts prefixes (e.g., 1000 Pa → 1 kPa) and reduces named units. Also provides the base SI representation.

ParametersJSON Schema

Name	Required	Description	Default
`expression`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses key behaviors: adjusting prefixes, reducing named units, and providing base SI. However, it could be more explicit about edge cases or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences totaling about 20 words, efficient and front-loaded with no superfluous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity and the presence of an output schema, the description adequately covers the main action. It explains what simplification entails and mentions base SI representation, but lacks details on valid input formats or handling of complex expressions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter 'expression' exists, and schema description coverage is 0%. The description simply refers to 'a unit expression' without adding details on format, valid units, or structure, providing marginal value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'simplify' and the resource 'unit expression', specifying it adjusts prefixes, reduces named units, and provides base SI representation. This distinguishes it from siblings like 'convert' and 'check_compatibility'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context but does not explicitly state when to use this tool versus alternatives like 'convert' or 'check_compatibility'. No when-not-to-use or prerequisite information is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

5 tool updatesv0.1.0Jul 13, 2026
- First observedcheck_compatibility
- First observedconvert
- First observedlist_compatible_units
- First observedparse_quantity
- First observedsimplify

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Disambiguation5/5

Each tool has a distinct, clearly defined purpose: checking compatibility, converting, listing compatible units, parsing strings, and simplifying expressions. No overlapping functionality.

Naming Consistency4/5

All tools use snake_case and follow a verb-based naming pattern. Most are verb_noun (check_compatibility, list_compatible_units, parse_quantity), while convert and simplify are single verbs, which is a minor inconsistency.

Tool Count5/5

With 5 tools, the server is well-scoped for unit operations. Each tool addresses a core need without unnecessary bloat.

Completeness4/5

The set covers essential operations: compatibility check, conversion, listing compatible units, parsing, and simplification. A minor gap is the lack of a tool to retrieve detailed unit metadata, but this is not critical.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
mcp AOAuth
io.scorecard
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
RAG Systems Monitoring Testing & QA Tools
3
TokenOracle
com.guffeyholdings
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
Finance Monitoring
2
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102

Related MCP Servers

gnomon-mcp
Calendar Management Developer Tools
lihtness
A
license
A
quality
C
maintenance
A small MCP server for the boring-but-essential utilities every model needs: dates, calendars, arithmetic, unit conversion. Use it so your assistant stops "next-token guessing" math and date math.
Updated 3 months ago (2026-05-26 12:21 UTC)
4
1
MIT
MCP Mathematics
Developer Tools Data Platforms
SHSharkar
A
license
C
quality
C
maintenance
A comprehensive MCP server that turns any AI assistant into a powerful mathematical computation engine, providing 52 advanced functions, 158 unit conversions, financial calculations, and secure AST-based evaluation.
Updated a year ago (2025-10-18 12:42 UTC)
18
13
MIT
Base Converter MCP
Developer Tools
vinkius-labs
F
license
Not graded
quality
C
maintenance
An MCP server providing deterministic base conversions (binary, hex, octal, decimal, base64) for AI agents, eliminating hallucination risks in low-level data processing.
Updated 3 months ago (2026-06-20 07:04 UTC)
18
3
-
CovAiLent
Research & Data
Mod26y
A
license
Not graded
quality
D
maintenance
An MCP server for chemistry-focused tools, enabling LLM agents to perform molecule parsing, format conversion, property lookup, and other chemistry operations with explainable responses.
Updated a year ago (2025-09-10 16:57 UTC)
Apache 2.0

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/quantumleeps/mcp-units'

If you have feedback or need assistance with the MCP directory API, please join our Discord server