Calculator Toolkit

Python MCP FastMCP FastAPI Uvicorn Tests Code style: black License Open Source Contributions Welcome

A versatile Model Context Protocol (MCP) server that provides calculator functionality through multiple transport modes. This toolkit supports STDIO, HTTP, and FastAPI transports, making it suitable for various integration scenarios from local CLI tools to web applications.

Features

• Multiple Transport Modes: Choose between STDIO, HTTP, or FastAPI based on your needs
• Four Basic Operations: Add, subtract, multiply, and divide
• MCP Protocol Support: Compatible with MCP Inspector and other MCP clients
• REST API: FastAPI mode provides both MCP and REST endpoints
• Modular Design: Easy to extend with new operations or transports
• Well Documented: Comprehensive inline documentation and examples

Available Operations

Operation	Description	MCP Tool Name
Addition	Add two numbers	add
Subtraction	Subtract two numbers	subtract
Multiplication	Multiply two numbers	multiply
Division	Divide two numbers	divide

Installation

1. Clone the repository:

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

2. Create a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Usage

STDIO Mode (Default)

STDIO mode is ideal for local CLI integration and testing. It communicates via standard input/output.

# Run in STDIO mode (default)
python main.py

# Or explicitly
python main.py --mode stdio

Testing with MCP Inspector:

npx @modelcontextprotocol/inspector python main.py --mode stdio

When the MCP Inspector opens:

1. The command will automatically use STDIO transport
2. Click "Connect" to test the calculator tools
3. Try invoking tools like add with arguments {"x": 5, "y": 3}

HTTP Mode

HTTP mode runs a local HTTP server suitable for web integrations.

# Run with default settings (localhost:8003)
python main.py --mode http

# Custom host and port
python main.py --mode http --host 0.0.0.0 --port 9000

Testing with MCP Inspector:

# Terminal 1: Start the server
python main.py --mode http

# Terminal 2: Test with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8003/mcp

Direct HTTP API calls:

# The HTTP mode uses MCP protocol over HTTP, not REST endpoints
# Use FastAPI mode for REST API access

FastAPI Mode

FastAPI mode provides both REST API endpoints and MCP tools, making it ideal for microservices or hybrid deployments.

# Run with default settings (localhost:8002) with MCP mounted
python main.py --mode fastapi

# Run as pure REST API without MCP
python main.py --mode fastapi --no-mcp

# Custom settings
python main.py --mode fastapi --host 0.0.0.0 --port 8080

Testing with MCP Inspector:

# Terminal 1: Start the server
python main.py --mode fastapi

# Terminal 2: Test with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8002/mcp

REST API Endpoints:

When running in FastAPI mode, the following REST endpoints are available:

# Addition
curl -X POST http://localhost:8002/add \
  -H "Content-Type: application/json" \
  -d '{"a": 5, "b": 3}'

# Subtraction
curl -X POST http://localhost:8002/subtract \
  -H "Content-Type: application/json" \
  -d '{"a": 10, "b": 4}'

# Multiplication
curl -X POST http://localhost:8002/multiply \
  -H "Content-Type: application/json" \
  -d '{"a": 7, "b": 6}'

# Division
curl -X POST http://localhost:8002/divide \
  -H "Content-Type: application/json" \
  -d '{"a": 20, "b": 4}'

# Health check
curl http://localhost:8002/health

Command-Line Options

python main.py --help

Available options:

• --mode {stdio,http,fastapi}: Transport mode (default: stdio)
• --host HOST: Host address for HTTP/FastAPI modes (default: localhost)
• --port PORT: Port number for HTTP/FastAPI modes
• --no-mcp: Disable MCP mounting in FastAPI mode
• --name NAME: Custom server name
• -v, --version: Show version information

Project Structure

mcp-calculator-toolkit/
├── src/
│   ├── __init__.py
│   ├── calculator.py          # Core calculator logic and tools
│   └── transports/
│       ├── __init__.py
│       ├── stdio.py          # STDIO transport implementation
│       ├── http.py           # HTTP transport implementation
│       └── fastapi_remote.py # FastAPI transport implementation
├── input_data/               # Input data directory (user files)
├── output_data/              # Output data directory (results)
├── main.py                   # Entry point with CLI
├── requirements.txt          # Python dependencies
└── README.md                 # This file

Testing with MCP Inspector

The MCP Inspector is the recommended tool for testing MCP servers.

Installation

npx @modelcontextprotocol/inspector --help

No installation required - it runs via npx.

Testing Different Modes

STDIO Mode:

npx @modelcontextprotocol/inspector python main.py --mode stdio

HTTP Mode:

# Start server first
python main.py --mode http &

# Then test
npx @modelcontextprotocol/inspector http://localhost:8003/mcp

FastAPI Mode:

# Start server first
python main.py --mode fastapi &

# Then test
npx @modelcontextprotocol/inspector http://localhost:8002/mcp

Using MCP Inspector

1. Connect: The inspector will automatically connect to your server
2. List Tools: Click to see available calculator tools
3. Invoke Tool: Select a tool (e.g., add) and provide JSON arguments:

   {
     "x": 10,
     "y": 5
   }
   

4. View Response: See the calculated result and any logs

Development

Adding New Operations

To add a new calculator operation:

1. Add the static method to src/calculator.py in the CalculatorTools class
2. Register it as an MCP tool in the register_calculator_tools function
3. Add a REST endpoint in src/transports/fastapi_remote.py if needed
4. Update this README with the new operation

Running Tests

# Install development dependencies
pip install pytest

# Run tests
pytest

Code Style

# Format with black
pip install black
black src/ main.py

# Lint with flake8
pip install flake8
flake8 src/ main.py

Data Directories

• input_data/: Place input files here if needed (tracked with .gitkeep)
• output_data/: Output files will be written here (tracked with .gitkeep)

Note: These directories are included in .gitignore for actual data files.

Requirements

• Python 3.8+
• Dependencies listed in requirements.txt

Security Notes

• By default, servers bind to localhost only for security
• Use --host 0.0.0.0 only if you need network access (not recommended for production without authentication)
• The FastAPI mode includes error handling to prevent information leakage

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

For issues or questions:

• Open an issue on GitHub
• Check existing issues for solutions

Acknowledgments

• Built with FastMCP
• Uses FastAPI for REST API mode
• MCP protocol by Anthropic