MCP Calculator Server

A Model Context Protocol (MCP) server that provides calculator functionality with robust mathematical operations. Built on the official go-sdk.

Features

Tools

• calculate: Mathematical operations with proper operator precedence, parentheses support, and scientific notation
• random_number: Generate random numbers within specified ranges using various probability distributions (uses elicitation when no distribution is given)

Both tools declare tool annotations (read-only, closed-world hints), titles, and structured output schemas.

Resources

• math://constants: Mathematical constants (π, e, φ, √2, ln2, ln10) in JSON format
• math://constants/{name}: Resource template — a single constant by name, e.g. math://constants/pi
• server://info: Server information and capabilities overview

Prompts

• math_problem: Generate mathematical word problems with configurable difficulty and topics
• explain_calculation: Step-by-step mathematical expression explanations

Protocol Features

• Completions: Argument completion for prompt arguments (difficulty, topic) and constant names in the resource template
• Elicitation: random_number asks the client which distribution to use when not specified
• Logging: Tool activity is forwarded to the client as MCP log messages (in addition to stderr)
• Icons & metadata: Server and tool icons, titles, website URL, and instructions

Transport Modes

• stdio: For local development and MCP Inspector integration
• streamable-http: For web deployments and container environments (with graceful shutdown)

Note: The HTTP transport binds all interfaces with no authentication or Origin validation — intended for demos and trusted networks only. Put it behind a reverse proxy (or use stdio) for anything else.

Default Behavior:

• Transport: streamable-http (if no TRANSPORT environment variable is set)
• Port: 8080 (configurable via PORT environment variable)

Installation

Prebuilt binaries for Linux, macOS, and Windows (amd64/arm64) are attached to each GitHub release.

Or install with Go:

go install github.com/yinebebt/mcp-calculator-server@latest

Usage

# Run with stdio
TRANSPORT=stdio mcp-calculator-server

# Run with HTTP (serves MCP at :8080/mcp, health check at /health)
mcp-calculator-server

# Test
go test ./...

MCP Client Configuration

For testing with MCP Client:

{
  "command": "/path/to/mcp-calculator-server",
  "env": {
    "TRANSPORT": "stdio"
  }
}

Mathematical Features

• Operator precedence: 2+3*4 = 14
• Parentheses: (2+3)*4 = 20
• Scientific notation: 1e2 = 100
• Error detection: Division by zero, invalid syntax, unmatched parentheses, non-finite results (NaN/Inf)

Release

Releases are built with GoReleaser via GitHub Actions. Pushing a vX.Y.Z tag cross-compiles for linux/darwin/windows × amd64/arm64 and attaches archives and checksums to the GitHub release.