Math MCP

$Python$ $MCP$ $FastAPI$ $License$

A comprehensive math utility server implementing the Model Context Protocol (MCP) over streamable HTTP. Designed primarily for reverse engineering workflows in tools like IDA Pro, Ghidra, x64dbg, and others — but equally useful as a general-purpose math sidekick for any LLM-powered coding assistant.

Features

Base conversion — decimal, hex, binary, octal, all at once
Bitwise operations — AND, OR, XOR, NOT, NAND, NOR
Bit shifts & rotates — logical, arithmetic, rotate left/right
Endianness — swap between little and big endian for 16/32/64-bit values
IEEE-754 floats — inspect float32/float64 sign, exponent, mantissa, bit layout
Struct packing — struct.pack / struct.unpack with arbitrary format strings
Bit fields — create masks, extract, set, clear, test arbitrary bit ranges
ASCII / Unicode — character to code point lookup, hex bytes to string
XOR cipher — XOR data with a repeating key (hex or string input)
GUID / UUID — parse mixed-endian GUID and RFC 4122 UUID from raw bytes
Timestamp conversion — FILETIME (NTFS), Unix, DOS timestamps
Hashing — MD5, SHA1, SHA256, SHA512
Hex dump — traditional format with ASCII sidebar
And more — CRC32, base64, sign extension, alignment, popcount, bit reverse, next power of 2

Tools Reference

Arithmetic

Tool	Description	Parameters	Returns	Example
`calc`	Basic arithmetic operations	`op` (enum: `add`, `sub`, `mul`, `div`, `mod`, `pow`, `sqrt`, `log`, `abs`, `neg`, `gcd`, `lcm`), `a` (string, first operand), `b` (string, second operand — omit for unary ops), `base` (number, log base, default: `2`)	Formatted result in all bases (if integer) or decimal string	`calc(op="add", a="0xFF", b="1")` → `dec: 256\nhex: 0x100\nbin: 0b100000000\noct: 0o400`

Number Conversion

Tool	Description	Parameters	Returns	Example
`convert`	Convert a number between bases	`value` (string, any base), `to` (enum: `dec`, `hex`, `bin`, `oct`, `all`, default: `all`)	Requested representation(s)	`convert(value="0xFF", to="dec")` → `255`
`compare`	Compare two numbers with diff/ratio	`a` (string), `b` (string)	Difference, signed values, ratio, relationship	`compare(a="0x100", b="0x80")` → shows a > b by 128

Bitwise & Shift

Tool	Description	Parameters	Returns	Example
`bitwise`	Bitwise AND / OR / XOR / NOT / NAND / NOR	`op` (enum: `and`, `or`, `xor`, `not`, `nand`, `nor`), `a` (string), `b` (string, omit for `not`), `width` (int, default: `32`)	Formatted result in all bases	`bitwise(op="xor", a="0xAB", b="0xCD")` → `dec: 102\nhex: 0x66\nbin: 0b1100110\noct: 0o146`
`shift`	Bit shift / rotate	`op` (enum: `shl`, `shr`, `sar`, `rol`, `ror`), `value` (string), `amount` (int), `width` (int, default: `32`)	Formatted result in all bases	`shift(op="rol", value="0x80000000", amount=1)` → `dec: 1\nhex: 0x1\n...`
`bitmask`	Create / extract / set / clear / test bit fields	`op` (enum: `mask`, `extract`, `set`, `clear`, `test`), `high_bit` (int), `low_bit` (int, default: `0`), `value` (string), `set_value` (string)	Mask value, extracted field, or modified value	`bitmask(op="mask", high_bit=7)` → `mask[7:0]:\ndec: 255\nhex: 0xFF\n...`
`popcount`	Count set bits	`value` (string), `width` (int, default: `32`)	Set/clear counts, density percentage	`popcount(value="0xFF")` → `set bits: 8\nclear bits: 24\ndensity: 25.0%`
`bit_reverse`	Reverse bit order	`value` (string), `width` (int, default: `32`)	Original and reversed binary	`bit_reverse(value="0x00000001")` → `reversed: 0x80000000`

Data Layout

Tool	Description	Parameters	Returns	Example
`endian`	Swap byte order (little ↔ big endian)	`value` (string), `width` (int, enum: `16`, `32`, `64`, default: `32`)	Byte-swapped value in all bases	`endian(value="0x12345678", width=32)` → `0x78563412`
`sign_extend`	Sign-extend from N to M bits	`value` (string), `from_bits` (int), `to_bits` (int, default: `64`)	Extended value with signed interpretation	`sign_extend(value="0x80", from_bits=8)` → `sign bit set — negative\nunsigned extended: 0xFFFFFFFFFFFFFF80\nsigned decimal: -128`
`pack`	Pack integer to bytes or unpack hex bytes	`op` (enum: `pack`, `unpack`), `fmt` (string, struct format), `value` (string)	Packed hex bytes or unpacked values	`pack(op="pack", fmt="<I", value="0xDEADBEEF")` → `bytes: EF BE AD DE`
`align`	Align value up/down to a power-of-2 boundary	`value` (string), `boundary` (string, must be power of 2), `direction` (enum: `up`, `down`, default: `up`)	Aligned value and difference	`align(value="0x1235", boundary=16)` → `aligned: 0x1240, difference: +11`

Float Analysis

Tool	Description	Parameters	Returns	Example
`float_bits`	Inspect IEEE-754 float32 or float64 bit layout	`value` (string — decimal float, hex, or binary), `width` (int, enum: `32`, `64`, default: `32`)	Sign, exponent, mantissa, hex, binary	`float_bits(value="3.14159", width=32)` → `sign=0 exp=128 mantissa=0x490FD0`

String & Encoding

Tool	Description	Parameters	Returns	Example
`ascii`	Character ↔ code point lookup	`value` (string — single char, decimal, hex, binary)	Character info or code point info	`ascii(value="A")` → `'A' → dec=65, hex=0x41, bin=0b01000001`
`string`	Convert hex bytes or comma-separated decimals to ASCII	`value` (string — hex or `12,34,56` format)	ASCII string and byte count	`string(value="48 65 6C 6C 6F")` → `ascii: Hello`
`base64`	Encode to or decode from base64	`op` (enum: `encode`, `decode`, default: `encode`), `value` (string)	Encoded or decoded result	`base64(op="encode", value="Hello")` → `SGVsbG8=`
`crc32`	Calculate CRC32 checksum	`value` (string — text or hex bytes)	CRC32 in hex and signed decimal	`crc32(value="Hello")` → `0xF7D18982`
`hash`	Calculate hash digest	`algo` (enum: `md5`, `sha1`, `sha256`, `sha512`, default: `md5`), `value` (string — text or hex bytes)	Hash hex digest	`hash(algo="sha256", value="Hello")` → `SHA256: 185F8DB3...`

Reverse Engineering Utilities

Tool	Description	Parameters	Returns	Example
`xor`	XOR cipher with repeating key	`value` (string — hex or text), `key` (string — hex or text)	XOR result in hex and ASCII	`xor(value="48656C6C6F", key="FF")` → `B79A939390`
`guid`	Parse/format GUID/UUID from raw bytes	`value` (string — hex bytes or GUID string like `xxxxxxxx-...`)	Mixed-endian GUID, RFC 4122 UUID, raw bytes	`guid(value="3B3E9B7A5C3D...")` → GUID/UUID/bytes
`timestamp`	Convert FILETIME / Unix / DOS timestamps	`value` (string), `type` (enum: `filetime`, `unix`, `dos`, default: `unix`)	Human-readable UTC and local time	`timestamp(value="0x1D2E3F4A", type="dos")` → DOS parsed date/time
`hexdump`	Format hex bytes as traditional hex dump	`value` (string — hex or text), `base` (string, base address, default: `0`)	Hex dump with ASCII sidebar	`hexdump(value="48656C6C6F")` → `00000000 48 65 6C 6C 6F ...
`next_pow2`	Find the next power of 2	`value` (string, must be positive)	Next and previous power of 2	`next_pow2(value="0x500")` → `next: 0x800 (2048)`

Getting Started

Prerequisites

Docker (recommended) — any modern Docker installation
or Python >= 3.14 with uv installed

Docker (recommended)

# Build the image
docker build -t math-mcp .

# Run in background, mapping host port 13338 to container port 3000
docker run -d -p 13338:3000 --name MathMCP --restart unless-stopped math-mcp

Native (Python 3.14+)

# Install uv (if not already installed)
pip install uv

# Sync dependencies
uv sync

# Run the server
uv run python server.py

Configuration

MCP Client Integration

Add to your MCP client configuration (e.g., ~/.config/opencode/opencode.json, claude_desktop_config.json, or Continue config):

{
  "mcpServers": {
    "math-mcp": {
      "type": "url",
      "url": "http://localhost:13338/mcp"
    }
  }
}

Environment / Arguments

The server listens on 0.0.0.0:3000 by default. To change the port, modify the uvicorn.run() call in server.py or the Docker port mapping.

API

The MCP endpoint uses the streamable HTTP transport (SSE + JSON-RPC).

Path	Method	Description
`/mcp`	POST	MCP JSON-RPC endpoint over SSE

Health check (FastAPI default):

curl http://localhost:13338/docs

Building from Source

git clone https://github.com/yourusername/math-mcp.git
cd math-mcp

# Development with hot reload
uv run uvicorn server:app --host 0.0.0.0 --port 3000 --reload

# Production via Docker
docker build -t math-mcp .
docker run -d -p 13338:3000 --name MathMCP math-mcp

Example: Tools in Action

Convert hex to all bases

Input:  convert(value="0xDEAD")
Output: dec: 57005
        hex: 0xDEAD
        bin: 0b1101111010101101
        oct: 0o157255

Inspect a float32

Input:  float_bits(value="3.14159", width=32)
Output: float32: 3.14159
        hex:  0x40490FD0
        bin:  0b01000000010010010000111111010000
        sign=0  exp=128 (unbiased 1)  mantissa=0x490FD0

XOR cipher

Input:  xor(value="48656C6C6F", key="FF")
Output: xor result (hex): B79A939390
        xor result (ascii): \xb7\x9a\x93\x93\x90

License

MIT — feel free to use, modify, and distribute.

Math MCP

Math MCP

Features

Tools Reference

Arithmetic

Number Conversion

Bitwise & Shift

Data Layout

Float Analysis

String & Encoding

Reverse Engineering Utilities

Getting Started

Prerequisites

Docker (recommended)

Native (Python 3.14+)

Configuration

MCP Client Integration

Environment / Arguments

API

Building from Source

Example: Tools in Action

Convert hex to all bases

Inspect a float32

XOR cipher

License

Latest Blog Posts

MCP directory API