Mathemagic

An AI calculator agent that interprets and solves science, technology, mathematics, and engineering problems in Python.

• Source Code
• pypi

Features

• Converts natural language math problems to Python code using LLMs (Claude is currently the only supported model)
• Handles units using the Pint library
• Provides access through MCP and CLI interfaces
• Supports complex mathematical operations with proper unit handling

Example Inputs

• "Convert 100 kilometers per hour to miles per hour"
• "What is the volume of a cylinder with radius 5cm and height 10cm?"
• "If I have 3 apples and 4 oranges, how many pieces of fruit do I have?"
• "Calculate the kinetic energy of a 2kg object moving at 10 meters per second"

Basic Usage

Enter command to start CLI

mathemagic

CLI initializes, and you type in your math problem

Quickstart

Installing Mathemagic

If you already installed uv, activated a virtual environment, and created a .env file with your Anthropic API key installation is simple:

uv add mathemagic-ai

If not, please see "Detailed Setup" for more info.

Detailed Setup

Creating an Anthropic Account

You'll also need an anthropic API key. This requires you set up a developer console, and add payment information. Running commands costs pennies.

To set up an account and get an API key:

1. Set up an account for the Anthropic Console
2. Add billing details
3. Buy credits (you can use the minumum)
4. Create an API key

*I may add support for other model providers in the future

Setting up API key as an Environment Variable

Create a .env file with your Anthropic API key in your project root directory.

If you already have a .env file, this command adds the api key.

echo "ANTHROPIC_API_KEY=your_api_key_here" >> .env

Installing uv & Setting Up a Virtual Environment

You can use pip if you prefer, but I highly recommend uv.

If you need to install uv, this is the basic command to install it on macOS and Linux. If it doesn't work, troubleshoot with instructions listed at installing uv.

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

I also higly recommend setting up a virtual environment.

# Create a virtual environment
uv venv
# Activate the virtual environment
source .venv/bin/activate
# Initialize the project with a pyproject.toml
uv init

Detailed CLI Usage

Example Usages

# Run in interactive mode
mathemagic

# Run the CLI with a math problem
mathemagic "100 miles times 234 acres in liters"

# Show the generated Python code along with the result
mathemagic "100 miles times 234 acres in liters" --output-python

# help menu
mathemagic --help

Output the Executed Python Code

Using the -p or --output-python flags

mathemagic -p

Mathemagic Calculator (Press Ctrl+C to exit)
Enter your math problem:
: Two hundred miles times 634 feet in meters squared.
Processing: Two hundred miles times 634 feet in meters squared.

Generated Python code:
```python
from pint import UnitRegistry

ureg = UnitRegistry()
Q_ = ureg.Quantity

# Define the variables with their respective units
miles = Q_(200, 'mile')  # distance in miles
feet = Q_(634, 'foot')  # distance in feet

# Perform the multiplication
result = miles * feet

# Convert the result to meters squared
result_m2 = result.to('meter**2')

print(result_m2)
```
Result:
62198956.89216 meter ** 2

Handles Arbitrary Units

mathemagic uses Pint to handle units.

Enter another problem:
: 100 bananas times 66 guavas
Processing: 100 bananas times 66 guavas

Result:
6600 banana * guava

Installation from Source (more advanced)

This is currently the only supported method for using the MCP server.

It's also advisable to do this from a virtual environment.

# Clone the repository
git clone https://github.com/yourusername/mathemagic.git
cd mathemagic

# Install dependencies using UV
uv pip install -e .

Starting the Server

# Start the MCP server
uv run src/mathemagic/server.py

Add the MCP Server to Claude Code

Assuming you have claude code installed, type this command, then follow the wizard. You'll enter the command above when prompted.

claude mcp add

Architecture

The application consists of:

• mathemagic.py: Core functionality for converting natural language to Python code and executing it
• server.py: MCP server that provides API endpoints for the calculator
• cli.py: Command-line interface for interacting with the calculator

TODO

1. Support for running MCP server with mathemagic installed as a package from pypi
2. Clean up python output through server (currently outputs in a dict and not pretty)
3. Improve CLI (make it pretty)
4. Update spec.md?
5. Add symbolic math support
6. Add linear algebra support
7. Update to use openrouter
8. Add tests
9. Astropy support?
10. Auth as alternative to .env for remote use?