Calculator Python Server

A simple MCP server built with FastMCP demonstrating calculator operations in Python

The Calculator Python server demonstrates building MCP servers with Python using the FastMCP framework. It provides basic arithmetic operations through a unified calculator tool.

Features

• FastMCP Framework: Simplified Python MCP development
• Arithmetic Operations: Add, subtract, multiply, divide
• Error Handling: Division by zero protection
• Minimal Setup: Quick to install and configure

Installation

1. Prerequisites

   Ensure you have Python 3.13+ installed:

   python --version
   
2. Navigate to Directory

   cd servers/calculator-py
   
3. Install Dependencies

   Install using uv (recommended) or pip:

   uv

   uv sync
   

   pip install "mcp[cli]>=1.6.0"
   
4. Configure MCP Client

   Add to your MCP client configuration:

   {
     "mcpServers": {
       "calculator-py": {
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/servers/calculator-py",
           "run",
           "server.py"
         ]
       }
     }
   }
   

Tools

calculate

Perform arithmetic operations on two numbers.

Parameters:

• a (float): First number
• b (float): Second number
• operation (string): Operation to perform - add, subtract, multiply, or divide

Example Usage:

Addition

{
  "a": 15,
  "b": 7,
  "operation": "add"
}
// Returns: 22.0

{
  "a": 15,
  "b": 7,
  "operation": "subtract"
}
// Returns: 8.0

{
  "a": 15,
  "b": 7,
  "operation": "multiply"
}
// Returns: 105.0

{
  "a": 15,
  "b": 3,
  "operation": "divide"
}
// Returns: 5.0

Implementation

Server Setup

The server uses FastMCP for simplified MCP server creation:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Calculator MCP Server")

Arithmetic Functions

Core calculator operations:

def add(a: float, b: float) -> float:
    return float(a + b)

def subtract(a: float, b: float) -> float:
    return float(a - b)

def multiply(a: float, b: float) -> float:
    return float(a * b)

def divide(a: float, b: float) -> float:
    if b == 0:
        raise ValueError("No se puede dividir por cero")
    return float(a / b)

Calculator Tool

Unified tool that routes to specific operations:

@mcp.tool()
def calculate(a: float, b: float, operation: str) -> float:
    """Perform arithmetic operations on two numbers.
    
    Args:
        a: First number
        b: Second number
        operation: Operation to perform (add, subtract, multiply, divide)
        
    Returns:
        Result of the calculation
        
    Raises:
        ValueError: If operation is invalid or division by zero
    """
    if operation == "add":
        return add(a, b)
    elif operation == "subtract":
        return subtract(a, b)
    elif operation == "multiply":
        return multiply(a, b)
    elif operation == "divide":
        return divide(a, b)
    else:
        raise ValueError("Operación no válida")

Running the Server

if __name__ == "__main__":
    mcp.run(transport='stdio')

Complete Server Code

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Calculator MCP Server")

def add(a: float, b: float) -> float:
    return float(a + b)

def subtract(a: float, b: float) -> float:
    return float(a - b)

def multiply(a: float, b: float) -> float:
    return float(a * b)

def divide(a: float, b: float) -> float:
    if b == 0:
        raise ValueError("No se puede dividir por cero")
    return float(a / b)

@mcp.tool()
def calculate(a: float, b: float, operation: str) -> float:
    if operation == "add":
        return add(a, b)
    elif operation == "subtract":
        return subtract(a, b)
    elif operation == "multiply":
        return multiply(a, b)
    elif operation == "divide":
        return divide(a, b)
    else:
        raise ValueError("Operación no válida")

if __name__ == "__main__":
    mcp.run(transport='stdio')

Error Handling

The calculator includes built-in error handling:

Division by Zero

# This will raise an error
{
  "a": 10,
  "b": 0,
  "operation": "divide"
}
# Error: "No se puede dividir por cero"

Invalid Operation

# This will raise an error
{
  "a": 10,
  "b": 5,
  "operation": "modulo"
}
# Error: "Operación no válida"

FastMCP Benefits

FastMCP simplifies MCP server development:

Decorator-Based

Use @mcp.tool() decorator to register tools automatically

Type Hints

Python type hints automatically define parameter schemas

Built-in Transport

Stdio transport configured with mcp.run(transport='stdio')

Error Handling

Automatic error serialization and reporting

Dependencies

pyproject.toml:

[project]
name = "calculator-py"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "mcp[cli]>=1.6.0",
]

Key Package:

• mcp[cli]>=1.6.0 - MCP SDK with CLI tools and FastMCP framework

Testing the Server

You can test the calculator using the MCP inspector:

uv run mcp dev server.py

Or test directly in your MCP client:

User: Calculate 144 divided by 12
Assistant: [Uses calculate tool]
Result: 12.0

Extending the Calculator

Add more operations by defining new functions and updating the tool:

def modulo(a: float, b: float) -> float:
    return float(a % b)

def power(a: float, b: float) -> float:
    return float(a ** b)

@mcp.tool()
def calculate(a: float, b: float, operation: str) -> float:
    operations = {
        "add": add,
        "subtract": subtract,
        "multiply": multiply,
        "divide": divide,
        "modulo": modulo,
        "power": power
    }
    
    if operation not in operations:
        raise ValueError(f"Operación no válida: {operation}")
    
    return operations[operation](a, b)

Troubleshooting

Python version error

This server requires Python 3.13+. Check your version:

python --version

Install Python 3.13+ from python.org if needed.

uv not found

Install uv for faster dependency management:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or use pip instead:

pip install "mcp[cli]>=1.6.0"
python server.py

Import errors

Ensure mcp package is installed:

uv pip list | grep mcp

Reinstall if needed:

uv sync --reinstall

Project Structure

calculator-py/
├── server.py             # Main server implementation
├── pyproject.toml        # Project configuration and dependencies
├── uv.lock              # Locked dependency versions
├── .python-version      # Python version specification
└── README.md            # Documentation

Next Steps

Basic TypeScript

Explore advanced MCP features with TypeScript

EDteam Go Server

Learn about API integration with Go MCP servers