# MCP Mathematics
A comprehensive Model Context Protocol (MCP) server that turns any AI assistant into a powerful mathematical computation engine. MCP Mathematics gives you professional-grade features including 52 advanced mathematical functions, 158 unit conversions across 15 categories, complete financial calculations, and secure AST-based evaluation—all in a production-ready, secure environment.
## What Is MCP Mathematics?
MCP Mathematics is the most complete mathematical computation server for AI assistants, built specifically for the Model Context Protocol. This production-ready solution turns any MCP-compatible AI into a powerful mathematical tool that handles everything from simple arithmetic to complex financial calculations, unit conversions across many different fields, and advanced scientific computations.
**Key Innovation**: Using Python's Abstract Syntax Tree (AST) evaluation, MCP Mathematics gives you exceptional mathematical capabilities while staying completely secure—stopping code injection vulnerabilities without losing any features.
## Why Choose MCP Mathematics?
### Uncompromising Security
- **AST-Based Evaluation**: Every calculation is checked and verified through Python's AST, which stops code injection attacks
- **Sandboxed Execution**: All calculations run in a secure, controlled environment that only allows safe operations
- **Zero External Dependencies**: Lower security risk since the core features don't need any external libraries
### Complete Mathematical Power
- **52 Built-In Functions**: From simple math to complex scientific calculations
- **158 Unit Conversions**: Wide-ranging unit conversion support covering 15 different categories
- **Financial Calculations**: Full set of financial tools including interest, loan, and tax calculations
- **Unicode Operator Support**: Easy mathematical symbols like ×, ÷, and ^ that feel natural to use
- **Full Math Library Coverage**: Complete access to all of Python's mathematical functions
### Production-Ready Architecture
- **Type-Safe Design**: Complete type checking throughout the code makes sure everything works reliably
- **Clean Production Code**: Professional code with no debugging leftovers or extra comments
- **Complete Testing**: 130 tests make sure all features work properly
- **Thread-Safe Operations**: 100% reliable concurrent execution with Timer-based timeout system
- **Advanced Memory Management**: Bounded LRU/TTL caches stop memory leaks in production environments
- **Enterprise Error Handling**: Proper exception chaining and graceful resource cleanup
## Getting Started
### Prerequisites
Before you install MCP Mathematics, make sure you have:
- Python 3.10 or later on your system
- An MCP-compatible AI assistant (Claude Desktop, VS Code with Continue, or similar)
### Installation Options
Choose the installation method that works best for you:
#### Option 1: Quick Install with uv (Recommended)
This is the fastest way to get started:
```bash
# Install the uv package manager if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install and run MCP Mathematics
uvx mcp-mathematics
```
#### Option 2: Traditional pip Installation
If you prefer using pip:
```bash
pip install mcp-mathematics
```
📦 **Package Information**: [mcp-mathematics on PyPI](https://pypi.org/project/mcp-mathematics)
#### Option 3: Development Installation
If you want to help out or need the latest development version:
```bash
git clone https://github.com/SHSharkar/MCP-Mathematics.git
cd MCP-Mathematics
pip install -e .
```
## Configuration Guide
### Configuring Claude Desktop
To use MCP Mathematics with Claude Desktop, you'll need to update your configuration file.
**Configuration file locations:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
#### If you installed with uv:
```json
{
"mcpServers": {
"mcp-mathematics": {
"command": "uvx",
"args": [
"mcp-mathematics"
]
}
}
}
```
#### If you installed with pip:
```json
{
"mcpServers": {
"mcp-mathematics": {
"command": "mcp-mathematics"
}
}
}
```
### Configuring VS Code with Continue
If you're using VS Code with the Continue extension:
```json
{
"models": [
{
"model": "claude-3-5-sonnet",
"provider": "anthropic",
"mcpServers": {
"mcp-mathematics": {
"command": "uvx",
"args": [
"mcp-mathematics"
]
}
}
}
]
}
```
### FastMCP Cloud Configuration
MCP Mathematics is available as a cloud-hosted service through FastMCP for instant access without local installation. Choose from multiple connection methods:
#### Connect to Claude Code
Access your tools from the command line with quick setup:
```bash
claude mcp add --scope local --transport http mathematics https://mathematics.fastmcp.app/mcp
```
#### Connect to Claude Desktop
Use your tools directly in Claude's desktop app with one-click installation:
**Download Link:** [https://mathematics.fastmcp.app/manifest.dxt?v=aa76634e-bffb-4be5-b1fd-c680cd7f7142](https://mathematics.fastmcp.app/manifest.dxt?v=aa76634e-bffb-4be5-b1fd-c680cd7f7142)
*Downloads .dxt file. Open the file to connect automatically.*
#### Connect to Codex CLI
Access your tools in a Codex CLI session:
```bash
codex mcp add -- mathematics npx -y mcp-remote@latest https://mathematics.fastmcp.app/mcp
```
#### Configure Codex
Durably store your MCP via Codex's configuration file by adding this to `.codex/config.toml`:
```toml
[mcp_servers.mathematics]
command = "npx"
args = ["-y", "mcp-remote@latest", "https://mathematics.fastmcp.app/mcp"]
```
#### Connect to Gemini CLI
Access your tools from the command line with quick setup:
```bash
gemini mcp add mathematics https://mathematics.fastmcp.app/mcp --transport http
```
#### Connect to Cursor
AI-powered code editor with built-in tool support. Click to connect instantly:
**Connection Link:** [cursor://anysphere.cursor-deeplink/mcp/install?name=mathematics&config=eyJ1cmwiOiJodHRwczovL21hdGhlbWF0aWNzLmZhc3RtY3AuYXBwL21jcCJ9](cursor://anysphere.cursor-deeplink/mcp/install?name=mathematics&config=eyJ1cmwiOiJodHRwczovL21hdGhlbWF0aWNzLmZhc3RtY3AuYXBwL21jcCJ9)
**FastMCP Cloud Benefits:**
- No local installation required
- Always up-to-date with latest features
- Enhanced performance with cloud infrastructure
- Instant access across multiple platforms
- Production-ready deployment
## Available MCP Tools
MCP Mathematics gives you access to all its mathematical features through 21 specialized tools with descriptive, mathematical domain names for maximum clarity and memorability. Each tool is designed for specific tasks and built for excellent performance:
### Core Calculation Tools
#### 1. `evaluate_mathematical_expression` - Single Expression Evaluation
The main tool for working with mathematical expressions. It supports all 52 built-in functions, unit conversions, and financial calculations. It handles everything from simple arithmetic to complex scientific computations.
**Use Cases:**
- Quick calculations: `"2 * pi * 10"` → `"62.83185307179586"`
- Scientific computing: `"sin(pi/2) + log10(1000)"` → `"4.0"`
- Financial analysis: `"compound_interest(5000, 6.5, 15)"` → Complete interest breakdown
- Unit conversions: `"convert_between_measurement_units(100, 'km', 'mi', 'length')"` → Automatic unit detection and conversion
#### 2. `evaluate_multiple_mathematical_expressions` - Parallel Processing Engine
Built to handle many expressions at the same time, giving you much better performance when doing lots of calculations or data analysis work.
**Use Cases:**
- Data processing: Process arrays of financial calculations
- Scientific analysis: Batch trigonometric computations
- Bulk conversions: Convert multiple values simultaneously
```
Input: ["sin(pi/2)", "cos(0)", "sqrt(16)", "factorial(5)"]
Output: ["1.0", "1.0", "4.0", "120"]
```
### Specialized Calculation Tools
#### 3. `convert_between_measurement_units` - Advanced Unit Conversion System
Smart unit conversion system that works with 158 units across 15 categories. It automatically figures out unit types, supports different spellings, and handles complex compound units.
**Advanced Features:**
- Smart detection: Automatically figures out unit categories
- Alias support: Accepts multiple spellings and abbreviations
- Compound units: Handles complex units like m/s², kg·m/s²
- History tracking: Keeps a conversion audit trail
```
Input: value=100, from_unit="meters", to_unit="feet"
Output: "328.084" (with automatic precision handling)
```
#### 4. `convert_units_from_natural_language` - Natural Language Unit Conversion
Converts units using natural language queries, making unit conversions more intuitive and accessible. This tool parses natural language requests and automatically determines the appropriate conversion.
**Supported Natural Language Patterns:**
- "convert 100 meters to feet"
- "what is 32 Celsius in Fahrenheit"
- "50 mph -> km/h"
- "5 kilograms equals how many pounds"
- "from 100 USD to EUR"
```
Input: "convert 100 kilometers to miles"
Output: {
"success": true,
"conversion": {
"original_query": "convert 100 kilometers to miles",
"input_value": 100,
"input_unit": "kilometers",
"output_value": 62.137119,
"output_unit": "miles",
"unit_type": "length"
}
}
```
#### 5. `compute_statistical_operations` - Statistical Analysis Engine
Performs comprehensive statistical calculations on datasets, providing essential statistical measures for data analysis and scientific computing.
**Available Statistical Operations:**
- Descriptive statistics: mean, median, mode, range
- Variability measures: variance, standard deviation
- Distribution analysis: skewness, kurtosis
- Data quality: quartiles, percentiles
```
Input: data=[1, 2, 3, 4, 5], operation="mean"
Output: "Result: 3.0"
```
#### 6. `perform_matrix_mathematical_operations` - Matrix Mathematics Engine
Advanced matrix operations for linear algebra, engineering calculations, and scientific computing with support for multiple matrix operations.
**Supported Matrix Operations:**
- Basic operations: multiply, transpose
- Advanced operations: determinant, inverse
- Matrix analysis: rank, eigenvalues (where applicable)
- Error handling for invalid operations
```
Input: matrices=[[[1,2],[3,4]], [[5,6],[7,8]]], operation="multiply"
Output: Matrix multiplication result with proper formatting
```
#### 7. `perform_number_theory_analysis` - Number Theory Analysis
Advanced number theory operations for mathematical research, cryptography, and computational mathematics.
**Available Number Theory Operations:**
- Prime testing: Check if numbers are prime
- Prime factorization: Find all prime factors
- Divisor analysis: Calculate all divisors
- Euler's totient: Compute φ(n) function
```
Input: n=97, operation="is_prime"
Output: "Result: 97 is prime"
```
### Session Management Tools
#### 8. `create_mathematical_calculation_session` - Session Initialization
Creates a new calculation session with optional initial variables, enabling stateful mathematical computations across multiple operations.
**Session Features:**
- Variable storage: Save and reuse calculation results
- State persistence: Maintain context across operations
- Isolated environments: Multiple independent sessions
- Custom initialization: Set initial variables
```
Input: session_id="analysis_1", variables={"x": 10, "pi": 3.14159}
Output: "Session created: analysis_1"
```
#### 9. `evaluate_expression_in_session_context` - Stateful Calculations
Performs calculations within a specific session context, with access to stored variables and the ability to save results for later use.
```
Input: session_id="analysis_1", expression="x * 2 + pi", save_as="result"
Output: "Result: 23.14159" (and saves as 'result' variable)
```
#### 10. `list_mathematical_session_variables` - Variable Management
Lists all variables currently stored in a calculation session, showing their names and values for easy reference.
```
Input: session_id="analysis_1"
Output: {"x": 10, "pi": 3.14159, "result": 23.14159}
```
#### 11. `delete_mathematical_calculation_session` - Session Cleanup
Safely removes a calculation session and all associated variables, freeing up memory and ensuring clean state management.
### System Monitoring Tools
#### 12. `get_mathematical_computation_performance_metrics` - Performance Monitoring
Provides comprehensive system performance metrics including computation statistics, memory usage, and operational uptime for monitoring system health.
**Metrics Included:**
- Computation statistics: Total calculations performed
- Performance data: Average response times
- Memory usage: Current memory consumption
- System uptime: Server operational time
#### 13. `get_mathematical_security_audit_report` - Security Information
Returns current security status including rate limiting information and session data for security monitoring and compliance.
#### 14. `get_mathematical_memory_usage_statistics` - Memory Analytics
Detailed memory usage statistics for cache and session management, helping with performance optimization and resource planning.
### Management and Discovery Tools
#### 15. `get_mathematical_computation_history` - Calculation Audit Trail
Keeps a complete record of all calculations with timestamps, so you can track, check, and repeat any mathematical work.
**Features:**
- Timestamped records: Every calculation includes when it was run
- Configurable limits: Get 1-100 recent calculations
- Expression tracking: Full input and output logging
- Error logging: Failed calculations with error details
#### 16. `clear_mathematical_computation_history` - History Management
Lets you safely clear your calculation history when you need to for privacy, performance, or storage reasons.
#### 17. `optimize_mathematical_computation_memory` - Memory Optimization
Cleans up expired cache entries and optimizes memory usage, helping maintain optimal performance in long-running sessions.
**Optimization Features:**
- Cache cleanup: Removes expired cache entries
- Memory defragmentation: Optimizes memory allocation
- Resource reclamation: Frees unused resources
- Performance improvement: Maintains system responsiveness
#### 18. `list_all_available_mathematical_functions_and_constants` - Complete Capability Discovery
Complete reference tool that gives you instant access to all available mathematical functions, constants, unit conversions, and their settings.
**Discovery Categories:**
- Mathematical functions: All 52 available functions with signatures
- Constants: Mathematical and physical constants with values
- Unit conversions: All 158 units organized by category
- System capabilities: Available operations and limits
**Note**: This tool consolidates the functionality of listing functions, constants, and recent history access in a single comprehensive interface.
## MCP Resources
Access these resources directly through the MCP protocol with their corresponding implementation functions:
- **`history://recent`** - View recent calculation history (implemented by `recent_calculation_history`)
- **`functions://available`** - Browse available mathematical functions (implemented by `mathematical_functions_catalog`)
- **`constants://math`** - Access mathematical constants with their values (implemented by `mathematical_constants_catalog`)
## MCP Prompts
Pre-configured prompts for common calculation patterns:
- **`scientific_calculation`** - Structured template for scientific computations
- **`batch_calculation`** - Optimized template for batch processing
## Mathematical Capabilities
MCP Mathematics gives you a complete mathematical computation environment with support for over 52 functions spanning basic arithmetic, advanced scientific computing, and specialized mathematical operations. The system handles everything from simple calculations to complex scientific and financial computations with precision and reliability.
### Basic Operations
Beyond standard arithmetic, MCP Mathematics supports easy-to-use mathematical operators including Unicode symbols for natural mathematical expression:
- Addition: `+`
- Subtraction: `-`
- Multiplication: `*` or `×`
- Division: `/` or `÷`
- Floor Division: `//`
- Modulo: `%`
- Exponentiation: `**` or `^`
### Complete Function Library
#### Trigonometric Functions
Essential trigonometric operations in radians:
- `sin(x)`, `cos(x)`, `tan(x)` - Standard trigonometric functions
- `asin(x)`, `acos(x)`, `atan(x)` - Inverse trigonometric functions
- `atan2(y, x)` - Two-argument arctangent for proper quadrant
#### Hyperbolic Functions
Complete hyperbolic function set:
- `sinh(x)`, `cosh(x)`, `tanh(x)` - Hyperbolic functions
- `asinh(x)`, `acosh(x)`, `atanh(x)` - Inverse hyperbolic functions
#### Logarithmic and Exponential Functions
Comprehensive logarithmic operations:
- `log(x)` - Natural logarithm
- `log10(x)` - Common logarithm (base 10)
- `log2(x)` - Binary logarithm
- `log1p(x)` - Natural logarithm of (1 + x) for precision
- `exp(x)` - Exponential function (e^x)
- `exp2(x)` - Base-2 exponential
- `expm1(x)` - Exponential minus 1 (e^x - 1)
- `sqrt(x)` - Square root
- `pow(x, y)` - Power function
#### Rounding and Precision
Control over numerical precision:
- `ceil(x)` - Round up to nearest integer
- `floor(x)` - Round down to nearest integer
- `trunc(x)` - Remove decimal portion
#### Special Mathematical Functions
Advanced mathematical operations:
- `factorial(x)` - Factorial computation
- `gamma(x)` - Gamma function
- `lgamma(x)` - Natural logarithm of gamma function
- `erf(x)` - Error function
- `erfc(x)` - Complementary error function
#### Number Theory
Integer and combinatorial mathematics:
- `gcd(x, y)` - Greatest common divisor
- `lcm(x, y)` - Least common multiple (Python 3.9+)
- `isqrt(x)` - Integer square root
- `comb(n, k)` - Binomial coefficient (combinations)
- `perm(n, k)` - Permutations
#### Floating-Point Operations
Precise control over floating-point arithmetic:
- `fabs(x)` - Floating-point absolute value
- `copysign(x, y)` - Magnitude of x with sign of y
- `fmod(x, y)` - Floating-point remainder
- `remainder(x, y)` - IEEE remainder operation
- `modf(x)` - Separate integer and fractional parts
- `frexp(x)` - Decompose into mantissa and exponent
- `ldexp(x, i)` - Compute x × 2^i efficiently
- `hypot(x, y)` - Euclidean distance calculation
- `cbrt(x)` - Cube root (Python 3.11+)
#### Numerical Comparison
Functions for numerical analysis:
- `isfinite(x)` - Check for finite values
- `isinf(x)` - Check for infinity
- `isnan(x)` - Check for Not-a-Number
- `isclose(a, b)` - Approximate equality testing
#### Advanced Numerical Functions
Specialized operations for scientific computing:
- `nextafter(x, y)` - Next representable floating-point value
- `ulp(x)` - Unit of least precision
#### Angle Conversion
Seamless conversion between angle units:
- `degrees(x)` - Convert radians to degrees
- `radians(x)` - Convert degrees to radians
### Mathematical Constants
Access fundamental mathematical constants:
- `pi` - π ≈ 3.141592653589793
- `e` - Euler's number ≈ 2.718281828459045
- `tau` - τ = 2π ≈ 6.283185307179586
- `inf` - Positive infinity
- `nan` - Not a Number
## Real-World Examples
### Basic Arithmetic
```python
evaluate_mathematical_expression("2 + 3 * 4") # Result: 14
evaluate_mathematical_expression("10 / 3") # Result: 3.3333333333333335
evaluate_mathematical_expression("2 ** 8") # Result: 256
```
### Scientific Computing
```python
evaluate_mathematical_expression("sin(pi/2)") # Result: 1.0
evaluate_mathematical_expression("log10(1000)") # Result: 3.0
evaluate_mathematical_expression("sqrt(16) + cos(0)") # Result: 5.0
```
### Complex Mathematical Expressions
```python
evaluate_mathematical_expression("(2 + 3) * sqrt(16) / sin(pi/2)") # Result: 20.0
evaluate_mathematical_expression("factorial(5) + gcd(12, 8)") # Result: 124
```
### Natural Mathematical Notation
```python
evaluate_mathematical_expression("5 × 3") # Result: 15
evaluate_mathematical_expression("20 ÷ 4") # Result: 5.0
evaluate_mathematical_expression("2 ^ 10") # Result: 1024
```
## Complete Unit Conversion System
MCP Mathematics includes a smart unit conversion system that works with 158 carefully calibrated units across 15 essential categories. This system does more than simple conversions—it provides smart unit detection, supports different spellings, handles complex compound units, and tracks your conversion history. This makes it perfect for scientific work, engineering calculations, and everyday conversions.
The conversion system automatically manages precision, accepts many different input formats, and works seamlessly with the mathematical expression engine for smooth integration in complex calculations.
### Supported Unit Categories
#### Length (15 units)
- Metric: `m`, `km`, `cm`, `mm`, `nm`, `micron`, `angstrom`
- Imperial: `mi`, `yd`, `ft`, `in`
- Astronomical: `ly` (light-years), `AU` (astronomical units), `pc` (parsecs)
- Nautical: `nmi` (nautical miles)
#### Mass (13 units)
- Metric: `kg`, `g`, `mg`, `ton` (metric), `t`
- Imperial: `lb`, `oz`, `ton_us` (short ton), `ton_uk` (long ton), `st` (stone)
- Special: `ct` (carats), `gr` (grains), `amu` (atomic mass units)
#### Time (15 units)
- Standard: `s`, `min`, `h`, `d`, `wk`, `mo`, `yr`
- Sub-second: `ms`, `us`, `ns`, `ps`
- Extended: `decade`, `century`, `millennium`, `fortnight`
#### Temperature (3 units)
- `K` (Kelvin), `C` (Celsius), `F` (Fahrenheit)
#### Area (12 units)
- Metric: `m2`, `km2`, `cm2`, `mm2`, `hectare`, `are`
- Imperial: `ft2`, `yd2`, `in2`, `mi2`, `acre`, `sqch` (square chains)
#### Volume (16 units)
- Metric: `L`, `mL`, `m3`, `cm3`
- US: `gal`, `qt`, `pt`, `fl_oz`, `cup`, `tbsp`, `tsp`
- UK: `gal_uk`, `qt_uk`, `pt_uk`
- Cubic: `ft3`, `in3`
#### Speed/Velocity (10 units)
- `m/s`, `km/h`, `mph`, `ft/s`, `knot`, `mach`, `cm/s`, `mi/min`, `in/s`, `c` (speed of light percentage)
#### Data/Digital Storage (16 units)
- Binary: `B`, `KB`, `MB`, `GB`, `TB`, `PB`, `EB`, `ZB`
- Bits: `bit`, `Kbit`, `Mbit`, `Gbit`, `Tbit`
- IEC: `KiB`, `MiB`, `GiB`
#### Pressure (10 units)
- `Pa`, `kPa`, `MPa`, `atm`, `bar`, `mbar`, `psi`, `torr`, `mmHg`, `inHg`
#### Energy (12 units)
- `J`, `kJ`, `MJ`, `cal`, `kcal`, `Wh`, `kWh`, `BTU`, `eV`, `ft_lb`, `erg`, `therm`
#### Power (10 units)
- `W`, `kW`, `MW`, `hp`, `PS`, `BTU/h`, `ft_lb/s`, `cal/s`, `erg/s`, `ton_refrigeration`
#### Force (8 units)
- `N`, `kN`, `lbf`, `kgf`, `dyne`, `pdl`, `ozf`, `tonf`
#### Angle (6 units)
- `deg`, `rad`, `grad`, `arcmin`, `arcsec`, `turn`
#### Frequency (6 units)
- `Hz`, `kHz`, `MHz`, `GHz`, `rpm`, `rad/s`
#### Fuel Economy (6 units)
- `mpg`, `mpg_uk`, `L/100km`, `km/L`, `mi/L`, `gal/100mi`
### Smart Features
#### Unit Aliases
MCP Mathematics supports common unit aliases for convenience:
```python
convert_between_measurement_units(
100, "kilometers", "miles", "length"
) # Works with full names
convert_between_measurement_units(100, "km", "mi", "length") # Works with abbreviations
convert_between_measurement_units(
100, "metre", "yard", "length"
) # Supports alternate spellings
```
#### Auto-Detection
The system automatically figures out unit types from context:
```python
convert_between_measurement_units(
100, "kg", "lb", "mass"
) # Automatically detects mass conversion
```
#### Compound Units
Parse and handle complex compound units:
```python
parse_compound_unit("m/s²") # Acceleration units
parse_compound_unit("kg·m/s²") # Force units
```
#### Scientific Notation
Automatic formatting for very large or small values:
```python
format_scientific_notation(0.000001, precision=2) # 1.00e-6
format_scientific_notation(1000000, precision=2) # 1.00e+6
```
#### Conversion History
Track all conversions with timestamps:
```python
convert_with_history(100, "m", "ft", precision=2) # Stores in history
conversion_history.get_recent(10) # Retrieve last 10
```
### Unit Conversion Examples
```python
# Length conversions
convert_between_measurement_units(100, "meters", "feet", "length") # 328.084
convert_between_measurement_units(1, "mile", "kilometers", "length") # 1.60934
# Mass conversions
convert_between_measurement_units(1, "kg", "pounds", "mass") # 2.20462
convert_between_measurement_units(100, "grams", "ounces", "mass") # 3.52740
# Temperature conversions
convert_between_measurement_units(0, "C", "F", "temperature") # 32
convert_between_measurement_units(100, "F", "C", "temperature") # 37.7778
# Data storage conversions
convert_between_measurement_units(1024, "MB", "GB", "data") # 1.024
convert_between_measurement_units(1, "TB", "bytes", "data") # 1099511627776
```
## Professional Financial Calculation Suite
MCP Mathematics includes a complete set of financial tools designed for professional use, education, and personal money management. The financial system supports advanced calculations including compound interest modeling, loan analysis, tax calculations, and business financial work.
All financial functions use high precision to make sure you get accurate money calculations and support different compounding frequencies, payment schedules, and tax situations you'll find in real-world financial work.
### Core Financial Functions
#### Percentage Operations
```python
calculate_percentage(1000, 15) # 150 (15% of 1000)
calculate_percentage_of(50, 200) # 25 (50 is 25% of 200)
calculate_percentage_change(100, 150) # 50 (50% increase)
```
#### Interest Calculations
```python
# Simple Interest
calculate_simple_interest(1000, 5, 10)
# Returns: {"interest": 500, "amount": 1500}
# Compound Interest
calculate_compound_interest(1000, 5, 10, 12) # Monthly compounding
# Returns: {"amount": 1647.01, "interest": 647.01}
```
#### Loan Calculations
```python
# Calculate monthly payment
calculate_loan_payment(100000, 5, 30, 12) # $100k, 5%, 30 years, monthly
# Returns: {"payment": 536.82, "total_paid": 193255.78, "interest_paid": 93255.78}
```
#### Tax Calculations
```python
# Calculate tax (inclusive or exclusive)
calculate_tax(100, 10, is_inclusive=False) # 10% tax on $100
# Returns: {"amount": 100, "tax": 10, "total": 110}
calculate_tax(110, 10, is_inclusive=True) # Price includes 10% tax
# Returns: {"amount": 100, "tax": 10, "total": 110}
```
#### Bill Operations
```python
# Split bill with tip
split_bill(100, 4, tip_percent=20)
# Returns: {"total": 120, "per_person": 30, "tip": 20}
# Calculate tip
calculate_tip(100, 18) # 18% tip on $100
# Returns: 18
```
#### Discount and Markup
```python
# Calculate discount
calculate_discount(100, 20) # 20% off $100
# Returns: {"original": 100, "discount": 20, "final": 80}
# Calculate markup
calculate_markup(100, 25) # 25% markup on $100 cost
# Returns: {"cost": 100, "markup": 25, "price": 125}
```
## Enterprise Architecture & Security
MCP Mathematics is built as an enterprise-grade mathematical computation platform that combines strong security measures with production-ready architecture. The system is designed to handle mission-critical calculations while maintaining the highest standards of code quality and security.
### Multi-Layered Security Framework
#### Core Security Principles
- **Zero-Trust Architecture**: Every input is checked and every operation is verified
- **Defense in Depth**: Multiple security layers give you complete protection
- **Principle of Least Privilege**: Only essential operations are allowed
- **Fail-Safe Defaults**: Safe defaults stop accidental security issues
#### Security Implementation
- **AST Evaluation Engine**: Every mathematical expression is processed through an Abstract Syntax Tree before evaluation, which stops code injection attacks while keeping full mathematical capability
- **Operation Whitelisting**: Only specifically approved mathematical operations and functions can run, which stops unauthorized code execution
- **Input Sanitization**: Thorough checking of all expressions and parameters before processing
- **Error Containment**: Complete error handling makes sure calculation failures don't affect system security
- **Dependency Minimization**: Core features need no external libraries, which greatly reduces security risks
### Production-Grade Architecture
#### Code Quality Standards
- **Type Safety**: Complete type annotations using Python 3.10+ features make sure you catch errors at compile-time
- **Clean Architecture**: Modular design with clear separation of concerns makes maintenance and scaling easier
- **Professional Codebase**: Production-ready code with no debug statements, console logs, or unnecessary comments
- **Complete Testing**: 130 unit tests give you thorough coverage across all mathematical functions and edge cases
- **Automated Quality**: Code standards enforced through Black formatting and Ruff linting
#### Performance & Reliability
- **Optimized Computation**: Efficient algorithms and data structures for high-performance calculations
- **Advanced Memory Management**: Bounded LRU and TTL cache systems with automatic cleanup stop memory leaks in long-running processes
- **Thread-Safe Concurrency**: 100% reliable concurrent execution using Timer-based timeouts instead of signal-based approaches
- **Session Management**: Graceful resource cleanup and session handling for enterprise environments
- **Error Recovery**: Proper exception chaining with better traceability for debugging and monitoring
- **Scalability**: Architecture designed to handle high-volume calculation workloads with concurrent processing
## Development Guide
This complete guide gives you everything you need to contribute to MCP Mathematics, from setting up your development environment to building production-ready distributions. The project follows strict quality standards and automated workflows to make sure everything works reliably and stays maintainable.
### Development Environment Setup
#### Prerequisites
```bash
# Ensure Python 3.10+ is installed
python --version # Should be 3.10 or higher
# Clone the repository
git clone https://github.com/SHSharkar/MCP-Mathematics.git
cd MCP-Mathematics
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install development dependencies
pip install -e ".[dev]"
```
### Quality Assurance Workflow
#### Running the Complete Test Suite
Run the comprehensive test suite covering all 130 test cases:
```bash
# Run all tests with detailed output
python -m pytest tests/ -v
# Run tests with coverage reporting
python -m pytest tests/ --cov=src --cov-report=html
# Run specific test categories
python -m pytest tests/test_calculator.py -v # Core functionality
python -m pytest tests/test_unit_conversion.py -v # Unit conversions
python -m pytest tests/test_financial.py -v # Financial calculations
```
#### Code Quality and Standards
Keep professional code standards with automated quality tools:
```bash
# Auto-format code with Black (100-character line limit)
black src/ tests/ --line-length 100
# Comprehensive linting with Ruff
ruff check src/ tests/ --fix
# Type checking with mypy
mypy src/
# Run complete pre-commit validation
pre-commit run --all-files
```
#### Performance and Security Validation
```bash
# Security analysis
bandit -r src/
# Performance profiling for mathematical operations
python -m cProfile -s cumtime scripts/benchmark.py
# Memory usage analysis
python -m memory_profiler scripts/memory_test.py
```
### Distribution and Deployment
#### Building Production Packages
Create optimized distribution packages for PyPI:
```bash
# Install build tools
pip install build twine
# Clean previous builds
rm -rf dist/ build/
# Build source and wheel distributions
python -m build
# Verify package integrity
twine check dist/*
# Test installation in clean environment
pip install dist/*.whl
```
#### Release Management
```bash
# Tag release version
git tag -a v1.0.0 -m "Release version 1.0.0"
# Push tags to trigger CI/CD
git push origin --tags
# Upload to PyPI (maintainers only)
twine upload dist/*
```
## Error Handling
MCP Mathematics gives you clear, helpful error messages to help you figure out what went wrong:
- **Syntax Errors**: Clear identification of malformed expressions
- **Division by Zero**: Smooth handling of mathematical impossibilities
- **Invalid Functions**: Helpful messages when unknown functions are called
- **Type Errors**: Detailed information about incompatible operations
- **Empty Expressions**: Helpful feedback when input is missing
## System Requirements
- Python 3.10 or higher
- MCP SDK 1.4.1 or later
## License
MCP Mathematics is released under the MIT License. Copyright © 2025 Md. Sazzad Hossain Sharkar
## Author
**Md. Sazzad Hossain Sharkar**
GitHub: [@SHSharkar](https://github.com/SHSharkar)
Email: md@szd.sh
## Contributing
We welcome contributions that maintain our high standards for code quality. When you contribute:
- Write clean, comment-free production code
- Include complete type annotations
- Add complete test coverage for new features
- Keep a clean, logical git history
## Acknowledgments
MCP Mathematics is built on the Model Context Protocol (MCP) specification developed by Anthropic, extending it with production-ready mathematical capabilities designed for professional use.
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-mathematics",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, api, assistant, calculator, chatgpt, claude, computation, converter, finance, formula, gpt, llm, math, mathematics, mcp, python, scientific, solver, tool, unit-conversion",
"author": null,
"author_email": "\"Md. Sazzad Hossain Sharkar\" <md@szd.sh>",
"download_url": "https://files.pythonhosted.org/packages/96/cc/34d4197e9dfc0982c0df9e38989af1d6b4709b1de964805614d474944092/mcp_mathematics-2.3.1.tar.gz",
"platform": null,
"description": "# MCP Mathematics\n\nA comprehensive Model Context Protocol (MCP) server that turns any AI assistant into a powerful mathematical computation engine. MCP Mathematics gives you professional-grade features including 52 advanced mathematical functions, 158 unit conversions across 15 categories, complete financial calculations, and secure AST-based evaluation\u2014all in a production-ready, secure environment.\n\n## What Is MCP Mathematics?\n\nMCP Mathematics is the most complete mathematical computation server for AI assistants, built specifically for the Model Context Protocol. This production-ready solution turns any MCP-compatible AI into a powerful mathematical tool that handles everything from simple arithmetic to complex financial calculations, unit conversions across many different fields, and advanced scientific computations.\n\n**Key Innovation**: Using Python's Abstract Syntax Tree (AST) evaluation, MCP Mathematics gives you exceptional mathematical capabilities while staying completely secure\u2014stopping code injection vulnerabilities without losing any features.\n\n## Why Choose MCP Mathematics?\n\n### Uncompromising Security\n\n- **AST-Based Evaluation**: Every calculation is checked and verified through Python's AST, which stops code injection attacks\n- **Sandboxed Execution**: All calculations run in a secure, controlled environment that only allows safe operations\n- **Zero External Dependencies**: Lower security risk since the core features don't need any external libraries\n\n### Complete Mathematical Power\n\n- **52 Built-In Functions**: From simple math to complex scientific calculations\n- **158 Unit Conversions**: Wide-ranging unit conversion support covering 15 different categories\n- **Financial Calculations**: Full set of financial tools including interest, loan, and tax calculations\n- **Unicode Operator Support**: Easy mathematical symbols like \u00d7, \u00f7, and ^ that feel natural to use\n- **Full Math Library Coverage**: Complete access to all of Python's mathematical functions\n\n### Production-Ready Architecture\n\n- **Type-Safe Design**: Complete type checking throughout the code makes sure everything works reliably\n- **Clean Production Code**: Professional code with no debugging leftovers or extra comments\n- **Complete Testing**: 130 tests make sure all features work properly\n- **Thread-Safe Operations**: 100% reliable concurrent execution with Timer-based timeout system\n- **Advanced Memory Management**: Bounded LRU/TTL caches stop memory leaks in production environments\n- **Enterprise Error Handling**: Proper exception chaining and graceful resource cleanup\n\n## Getting Started\n\n### Prerequisites\n\nBefore you install MCP Mathematics, make sure you have:\n\n- Python 3.10 or later on your system\n- An MCP-compatible AI assistant (Claude Desktop, VS Code with Continue, or similar)\n\n### Installation Options\n\nChoose the installation method that works best for you:\n\n#### Option 1: Quick Install with uv (Recommended)\n\nThis is the fastest way to get started:\n\n```bash\n# Install the uv package manager if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install and run MCP Mathematics\nuvx mcp-mathematics\n```\n\n#### Option 2: Traditional pip Installation\n\nIf you prefer using pip:\n\n```bash\npip install mcp-mathematics\n```\n\n\ud83d\udce6 **Package Information**: [mcp-mathematics on PyPI](https://pypi.org/project/mcp-mathematics)\n\n#### Option 3: Development Installation\n\nIf you want to help out or need the latest development version:\n\n```bash\ngit clone https://github.com/SHSharkar/MCP-Mathematics.git\ncd MCP-Mathematics\npip install -e .\n```\n\n## Configuration Guide\n\n### Configuring Claude Desktop\n\nTo use MCP Mathematics with Claude Desktop, you'll need to update your configuration file.\n\n**Configuration file locations:**\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n#### If you installed with uv:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-mathematics\": {\n \"command\": \"uvx\",\n \"args\": [\n \"mcp-mathematics\"\n ]\n }\n }\n}\n```\n\n#### If you installed with pip:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-mathematics\": {\n \"command\": \"mcp-mathematics\"\n }\n }\n}\n```\n\n### Configuring VS Code with Continue\n\nIf you're using VS Code with the Continue extension:\n\n```json\n{\n \"models\": [\n {\n \"model\": \"claude-3-5-sonnet\",\n \"provider\": \"anthropic\",\n \"mcpServers\": {\n \"mcp-mathematics\": {\n \"command\": \"uvx\",\n \"args\": [\n \"mcp-mathematics\"\n ]\n }\n }\n }\n ]\n}\n```\n\n### FastMCP Cloud Configuration\n\nMCP Mathematics is available as a cloud-hosted service through FastMCP for instant access without local installation. Choose from multiple connection methods:\n\n#### Connect to Claude Code\n\nAccess your tools from the command line with quick setup:\n\n```bash\nclaude mcp add --scope local --transport http mathematics https://mathematics.fastmcp.app/mcp\n```\n\n#### Connect to Claude Desktop\n\nUse your tools directly in Claude's desktop app with one-click installation:\n\n**Download Link:** [https://mathematics.fastmcp.app/manifest.dxt?v=aa76634e-bffb-4be5-b1fd-c680cd7f7142](https://mathematics.fastmcp.app/manifest.dxt?v=aa76634e-bffb-4be5-b1fd-c680cd7f7142)\n\n*Downloads .dxt file. Open the file to connect automatically.*\n\n#### Connect to Codex CLI\n\nAccess your tools in a Codex CLI session:\n\n```bash\ncodex mcp add -- mathematics npx -y mcp-remote@latest https://mathematics.fastmcp.app/mcp\n```\n\n#### Configure Codex\n\nDurably store your MCP via Codex's configuration file by adding this to `.codex/config.toml`:\n\n```toml\n[mcp_servers.mathematics]\ncommand = \"npx\"\nargs = [\"-y\", \"mcp-remote@latest\", \"https://mathematics.fastmcp.app/mcp\"]\n```\n\n#### Connect to Gemini CLI\n\nAccess your tools from the command line with quick setup:\n\n```bash\ngemini mcp add mathematics https://mathematics.fastmcp.app/mcp --transport http\n```\n\n#### Connect to Cursor\n\nAI-powered code editor with built-in tool support. Click to connect instantly:\n\n**Connection Link:** [cursor://anysphere.cursor-deeplink/mcp/install?name=mathematics&config=eyJ1cmwiOiJodHRwczovL21hdGhlbWF0aWNzLmZhc3RtY3AuYXBwL21jcCJ9](cursor://anysphere.cursor-deeplink/mcp/install?name=mathematics&config=eyJ1cmwiOiJodHRwczovL21hdGhlbWF0aWNzLmZhc3RtY3AuYXBwL21jcCJ9)\n\n**FastMCP Cloud Benefits:**\n\n- No local installation required\n- Always up-to-date with latest features\n- Enhanced performance with cloud infrastructure\n- Instant access across multiple platforms\n- Production-ready deployment\n\n## Available MCP Tools\n\nMCP Mathematics gives you access to all its mathematical features through 21 specialized tools with descriptive, mathematical domain names for maximum clarity and memorability. Each tool is designed for specific tasks and built for excellent performance:\n\n### Core Calculation Tools\n\n#### 1. `evaluate_mathematical_expression` - Single Expression Evaluation\n\nThe main tool for working with mathematical expressions. It supports all 52 built-in functions, unit conversions, and financial calculations. It handles everything from simple arithmetic to complex scientific computations.\n\n**Use Cases:**\n\n- Quick calculations: `\"2 * pi * 10\"` \u2192 `\"62.83185307179586\"`\n- Scientific computing: `\"sin(pi/2) + log10(1000)\"` \u2192 `\"4.0\"`\n- Financial analysis: `\"compound_interest(5000, 6.5, 15)\"` \u2192 Complete interest breakdown\n- Unit conversions: `\"convert_between_measurement_units(100, 'km', 'mi', 'length')\"` \u2192 Automatic unit detection and conversion\n\n#### 2. `evaluate_multiple_mathematical_expressions` - Parallel Processing Engine\n\nBuilt to handle many expressions at the same time, giving you much better performance when doing lots of calculations or data analysis work.\n\n**Use Cases:**\n\n- Data processing: Process arrays of financial calculations\n- Scientific analysis: Batch trigonometric computations\n- Bulk conversions: Convert multiple values simultaneously\n\n```\nInput: [\"sin(pi/2)\", \"cos(0)\", \"sqrt(16)\", \"factorial(5)\"]\nOutput: [\"1.0\", \"1.0\", \"4.0\", \"120\"]\n```\n\n### Specialized Calculation Tools\n\n#### 3. `convert_between_measurement_units` - Advanced Unit Conversion System\n\nSmart unit conversion system that works with 158 units across 15 categories. It automatically figures out unit types, supports different spellings, and handles complex compound units.\n\n**Advanced Features:**\n\n- Smart detection: Automatically figures out unit categories\n- Alias support: Accepts multiple spellings and abbreviations\n- Compound units: Handles complex units like m/s\u00b2, kg\u00b7m/s\u00b2\n- History tracking: Keeps a conversion audit trail\n\n```\nInput: value=100, from_unit=\"meters\", to_unit=\"feet\"\nOutput: \"328.084\" (with automatic precision handling)\n```\n\n#### 4. `convert_units_from_natural_language` - Natural Language Unit Conversion\n\nConverts units using natural language queries, making unit conversions more intuitive and accessible. This tool parses natural language requests and automatically determines the appropriate conversion.\n\n**Supported Natural Language Patterns:**\n\n- \"convert 100 meters to feet\"\n- \"what is 32 Celsius in Fahrenheit\"\n- \"50 mph -> km/h\"\n- \"5 kilograms equals how many pounds\"\n- \"from 100 USD to EUR\"\n\n```\nInput: \"convert 100 kilometers to miles\"\nOutput: {\n \"success\": true,\n \"conversion\": {\n \"original_query\": \"convert 100 kilometers to miles\",\n \"input_value\": 100,\n \"input_unit\": \"kilometers\",\n \"output_value\": 62.137119,\n \"output_unit\": \"miles\",\n \"unit_type\": \"length\"\n }\n}\n```\n\n#### 5. `compute_statistical_operations` - Statistical Analysis Engine\n\nPerforms comprehensive statistical calculations on datasets, providing essential statistical measures for data analysis and scientific computing.\n\n**Available Statistical Operations:**\n\n- Descriptive statistics: mean, median, mode, range\n- Variability measures: variance, standard deviation\n- Distribution analysis: skewness, kurtosis\n- Data quality: quartiles, percentiles\n\n```\nInput: data=[1, 2, 3, 4, 5], operation=\"mean\"\nOutput: \"Result: 3.0\"\n```\n\n#### 6. `perform_matrix_mathematical_operations` - Matrix Mathematics Engine\n\nAdvanced matrix operations for linear algebra, engineering calculations, and scientific computing with support for multiple matrix operations.\n\n**Supported Matrix Operations:**\n\n- Basic operations: multiply, transpose\n- Advanced operations: determinant, inverse\n- Matrix analysis: rank, eigenvalues (where applicable)\n- Error handling for invalid operations\n\n```\nInput: matrices=[[[1,2],[3,4]], [[5,6],[7,8]]], operation=\"multiply\"\nOutput: Matrix multiplication result with proper formatting\n```\n\n#### 7. `perform_number_theory_analysis` - Number Theory Analysis\n\nAdvanced number theory operations for mathematical research, cryptography, and computational mathematics.\n\n**Available Number Theory Operations:**\n\n- Prime testing: Check if numbers are prime\n- Prime factorization: Find all prime factors\n- Divisor analysis: Calculate all divisors\n- Euler's totient: Compute \u03c6(n) function\n\n```\nInput: n=97, operation=\"is_prime\"\nOutput: \"Result: 97 is prime\"\n```\n\n### Session Management Tools\n\n#### 8. `create_mathematical_calculation_session` - Session Initialization\n\nCreates a new calculation session with optional initial variables, enabling stateful mathematical computations across multiple operations.\n\n**Session Features:**\n\n- Variable storage: Save and reuse calculation results\n- State persistence: Maintain context across operations\n- Isolated environments: Multiple independent sessions\n- Custom initialization: Set initial variables\n\n```\nInput: session_id=\"analysis_1\", variables={\"x\": 10, \"pi\": 3.14159}\nOutput: \"Session created: analysis_1\"\n```\n\n#### 9. `evaluate_expression_in_session_context` - Stateful Calculations\n\nPerforms calculations within a specific session context, with access to stored variables and the ability to save results for later use.\n\n```\nInput: session_id=\"analysis_1\", expression=\"x * 2 + pi\", save_as=\"result\"\nOutput: \"Result: 23.14159\" (and saves as 'result' variable)\n```\n\n#### 10. `list_mathematical_session_variables` - Variable Management\n\nLists all variables currently stored in a calculation session, showing their names and values for easy reference.\n\n```\nInput: session_id=\"analysis_1\"\nOutput: {\"x\": 10, \"pi\": 3.14159, \"result\": 23.14159}\n```\n\n#### 11. `delete_mathematical_calculation_session` - Session Cleanup\n\nSafely removes a calculation session and all associated variables, freeing up memory and ensuring clean state management.\n\n### System Monitoring Tools\n\n#### 12. `get_mathematical_computation_performance_metrics` - Performance Monitoring\n\nProvides comprehensive system performance metrics including computation statistics, memory usage, and operational uptime for monitoring system health.\n\n**Metrics Included:**\n\n- Computation statistics: Total calculations performed\n- Performance data: Average response times\n- Memory usage: Current memory consumption\n- System uptime: Server operational time\n\n#### 13. `get_mathematical_security_audit_report` - Security Information\n\nReturns current security status including rate limiting information and session data for security monitoring and compliance.\n\n#### 14. `get_mathematical_memory_usage_statistics` - Memory Analytics\n\nDetailed memory usage statistics for cache and session management, helping with performance optimization and resource planning.\n\n### Management and Discovery Tools\n\n#### 15. `get_mathematical_computation_history` - Calculation Audit Trail\n\nKeeps a complete record of all calculations with timestamps, so you can track, check, and repeat any mathematical work.\n\n**Features:**\n\n- Timestamped records: Every calculation includes when it was run\n- Configurable limits: Get 1-100 recent calculations\n- Expression tracking: Full input and output logging\n- Error logging: Failed calculations with error details\n\n#### 16. `clear_mathematical_computation_history` - History Management\n\nLets you safely clear your calculation history when you need to for privacy, performance, or storage reasons.\n\n#### 17. `optimize_mathematical_computation_memory` - Memory Optimization\n\nCleans up expired cache entries and optimizes memory usage, helping maintain optimal performance in long-running sessions.\n\n**Optimization Features:**\n\n- Cache cleanup: Removes expired cache entries\n- Memory defragmentation: Optimizes memory allocation\n- Resource reclamation: Frees unused resources\n- Performance improvement: Maintains system responsiveness\n\n#### 18. `list_all_available_mathematical_functions_and_constants` - Complete Capability Discovery\n\nComplete reference tool that gives you instant access to all available mathematical functions, constants, unit conversions, and their settings.\n\n**Discovery Categories:**\n\n- Mathematical functions: All 52 available functions with signatures\n- Constants: Mathematical and physical constants with values\n- Unit conversions: All 158 units organized by category\n- System capabilities: Available operations and limits\n\n**Note**: This tool consolidates the functionality of listing functions, constants, and recent history access in a single comprehensive interface.\n\n## MCP Resources\n\nAccess these resources directly through the MCP protocol with their corresponding implementation functions:\n\n- **`history://recent`** - View recent calculation history (implemented by `recent_calculation_history`)\n- **`functions://available`** - Browse available mathematical functions (implemented by `mathematical_functions_catalog`)\n- **`constants://math`** - Access mathematical constants with their values (implemented by `mathematical_constants_catalog`)\n\n## MCP Prompts\n\nPre-configured prompts for common calculation patterns:\n\n- **`scientific_calculation`** - Structured template for scientific computations\n- **`batch_calculation`** - Optimized template for batch processing\n\n## Mathematical Capabilities\n\nMCP Mathematics gives you a complete mathematical computation environment with support for over 52 functions spanning basic arithmetic, advanced scientific computing, and specialized mathematical operations. The system handles everything from simple calculations to complex scientific and financial computations with precision and reliability.\n\n### Basic Operations\n\nBeyond standard arithmetic, MCP Mathematics supports easy-to-use mathematical operators including Unicode symbols for natural mathematical expression:\n\n- Addition: `+`\n- Subtraction: `-`\n- Multiplication: `*` or `\u00d7`\n- Division: `/` or `\u00f7`\n- Floor Division: `//`\n- Modulo: `%`\n- Exponentiation: `**` or `^`\n\n### Complete Function Library\n\n#### Trigonometric Functions\n\nEssential trigonometric operations in radians:\n\n- `sin(x)`, `cos(x)`, `tan(x)` - Standard trigonometric functions\n- `asin(x)`, `acos(x)`, `atan(x)` - Inverse trigonometric functions\n- `atan2(y, x)` - Two-argument arctangent for proper quadrant\n\n#### Hyperbolic Functions\n\nComplete hyperbolic function set:\n\n- `sinh(x)`, `cosh(x)`, `tanh(x)` - Hyperbolic functions\n- `asinh(x)`, `acosh(x)`, `atanh(x)` - Inverse hyperbolic functions\n\n#### Logarithmic and Exponential Functions\n\nComprehensive logarithmic operations:\n\n- `log(x)` - Natural logarithm\n- `log10(x)` - Common logarithm (base 10)\n- `log2(x)` - Binary logarithm\n- `log1p(x)` - Natural logarithm of (1 + x) for precision\n- `exp(x)` - Exponential function (e^x)\n- `exp2(x)` - Base-2 exponential\n- `expm1(x)` - Exponential minus 1 (e^x - 1)\n- `sqrt(x)` - Square root\n- `pow(x, y)` - Power function\n\n#### Rounding and Precision\n\nControl over numerical precision:\n\n- `ceil(x)` - Round up to nearest integer\n- `floor(x)` - Round down to nearest integer\n- `trunc(x)` - Remove decimal portion\n\n#### Special Mathematical Functions\n\nAdvanced mathematical operations:\n\n- `factorial(x)` - Factorial computation\n- `gamma(x)` - Gamma function\n- `lgamma(x)` - Natural logarithm of gamma function\n- `erf(x)` - Error function\n- `erfc(x)` - Complementary error function\n\n#### Number Theory\n\nInteger and combinatorial mathematics:\n\n- `gcd(x, y)` - Greatest common divisor\n- `lcm(x, y)` - Least common multiple (Python 3.9+)\n- `isqrt(x)` - Integer square root\n- `comb(n, k)` - Binomial coefficient (combinations)\n- `perm(n, k)` - Permutations\n\n#### Floating-Point Operations\n\nPrecise control over floating-point arithmetic:\n\n- `fabs(x)` - Floating-point absolute value\n- `copysign(x, y)` - Magnitude of x with sign of y\n- `fmod(x, y)` - Floating-point remainder\n- `remainder(x, y)` - IEEE remainder operation\n- `modf(x)` - Separate integer and fractional parts\n- `frexp(x)` - Decompose into mantissa and exponent\n- `ldexp(x, i)` - Compute x \u00d7 2^i efficiently\n- `hypot(x, y)` - Euclidean distance calculation\n- `cbrt(x)` - Cube root (Python 3.11+)\n\n#### Numerical Comparison\n\nFunctions for numerical analysis:\n\n- `isfinite(x)` - Check for finite values\n- `isinf(x)` - Check for infinity\n- `isnan(x)` - Check for Not-a-Number\n- `isclose(a, b)` - Approximate equality testing\n\n#### Advanced Numerical Functions\n\nSpecialized operations for scientific computing:\n\n- `nextafter(x, y)` - Next representable floating-point value\n- `ulp(x)` - Unit of least precision\n\n#### Angle Conversion\n\nSeamless conversion between angle units:\n\n- `degrees(x)` - Convert radians to degrees\n- `radians(x)` - Convert degrees to radians\n\n### Mathematical Constants\n\nAccess fundamental mathematical constants:\n\n- `pi` - \u03c0 \u2248 3.141592653589793\n- `e` - Euler's number \u2248 2.718281828459045\n- `tau` - \u03c4 = 2\u03c0 \u2248 6.283185307179586\n- `inf` - Positive infinity\n- `nan` - Not a Number\n\n## Real-World Examples\n\n### Basic Arithmetic\n\n```python\nevaluate_mathematical_expression(\"2 + 3 * 4\") # Result: 14\nevaluate_mathematical_expression(\"10 / 3\") # Result: 3.3333333333333335\nevaluate_mathematical_expression(\"2 ** 8\") # Result: 256\n```\n\n### Scientific Computing\n\n```python\nevaluate_mathematical_expression(\"sin(pi/2)\") # Result: 1.0\nevaluate_mathematical_expression(\"log10(1000)\") # Result: 3.0\nevaluate_mathematical_expression(\"sqrt(16) + cos(0)\") # Result: 5.0\n```\n\n### Complex Mathematical Expressions\n\n```python\nevaluate_mathematical_expression(\"(2 + 3) * sqrt(16) / sin(pi/2)\") # Result: 20.0\nevaluate_mathematical_expression(\"factorial(5) + gcd(12, 8)\") # Result: 124\n```\n\n### Natural Mathematical Notation\n\n```python\nevaluate_mathematical_expression(\"5 \u00d7 3\") # Result: 15\nevaluate_mathematical_expression(\"20 \u00f7 4\") # Result: 5.0\nevaluate_mathematical_expression(\"2 ^ 10\") # Result: 1024\n```\n\n## Complete Unit Conversion System\n\nMCP Mathematics includes a smart unit conversion system that works with 158 carefully calibrated units across 15 essential categories. This system does more than simple conversions\u2014it provides smart unit detection, supports different spellings, handles complex compound units, and tracks your conversion history. This makes it perfect for scientific work, engineering calculations, and everyday conversions.\n\nThe conversion system automatically manages precision, accepts many different input formats, and works seamlessly with the mathematical expression engine for smooth integration in complex calculations.\n\n### Supported Unit Categories\n\n#### Length (15 units)\n\n- Metric: `m`, `km`, `cm`, `mm`, `nm`, `micron`, `angstrom`\n- Imperial: `mi`, `yd`, `ft`, `in`\n- Astronomical: `ly` (light-years), `AU` (astronomical units), `pc` (parsecs)\n- Nautical: `nmi` (nautical miles)\n\n#### Mass (13 units)\n\n- Metric: `kg`, `g`, `mg`, `ton` (metric), `t`\n- Imperial: `lb`, `oz`, `ton_us` (short ton), `ton_uk` (long ton), `st` (stone)\n- Special: `ct` (carats), `gr` (grains), `amu` (atomic mass units)\n\n#### Time (15 units)\n\n- Standard: `s`, `min`, `h`, `d`, `wk`, `mo`, `yr`\n- Sub-second: `ms`, `us`, `ns`, `ps`\n- Extended: `decade`, `century`, `millennium`, `fortnight`\n\n#### Temperature (3 units)\n\n- `K` (Kelvin), `C` (Celsius), `F` (Fahrenheit)\n\n#### Area (12 units)\n\n- Metric: `m2`, `km2`, `cm2`, `mm2`, `hectare`, `are`\n- Imperial: `ft2`, `yd2`, `in2`, `mi2`, `acre`, `sqch` (square chains)\n\n#### Volume (16 units)\n\n- Metric: `L`, `mL`, `m3`, `cm3`\n- US: `gal`, `qt`, `pt`, `fl_oz`, `cup`, `tbsp`, `tsp`\n- UK: `gal_uk`, `qt_uk`, `pt_uk`\n- Cubic: `ft3`, `in3`\n\n#### Speed/Velocity (10 units)\n\n- `m/s`, `km/h`, `mph`, `ft/s`, `knot`, `mach`, `cm/s`, `mi/min`, `in/s`, `c` (speed of light percentage)\n\n#### Data/Digital Storage (16 units)\n\n- Binary: `B`, `KB`, `MB`, `GB`, `TB`, `PB`, `EB`, `ZB`\n- Bits: `bit`, `Kbit`, `Mbit`, `Gbit`, `Tbit`\n- IEC: `KiB`, `MiB`, `GiB`\n\n#### Pressure (10 units)\n\n- `Pa`, `kPa`, `MPa`, `atm`, `bar`, `mbar`, `psi`, `torr`, `mmHg`, `inHg`\n\n#### Energy (12 units)\n\n- `J`, `kJ`, `MJ`, `cal`, `kcal`, `Wh`, `kWh`, `BTU`, `eV`, `ft_lb`, `erg`, `therm`\n\n#### Power (10 units)\n\n- `W`, `kW`, `MW`, `hp`, `PS`, `BTU/h`, `ft_lb/s`, `cal/s`, `erg/s`, `ton_refrigeration`\n\n#### Force (8 units)\n\n- `N`, `kN`, `lbf`, `kgf`, `dyne`, `pdl`, `ozf`, `tonf`\n\n#### Angle (6 units)\n\n- `deg`, `rad`, `grad`, `arcmin`, `arcsec`, `turn`\n\n#### Frequency (6 units)\n\n- `Hz`, `kHz`, `MHz`, `GHz`, `rpm`, `rad/s`\n\n#### Fuel Economy (6 units)\n\n- `mpg`, `mpg_uk`, `L/100km`, `km/L`, `mi/L`, `gal/100mi`\n\n### Smart Features\n\n#### Unit Aliases\n\nMCP Mathematics supports common unit aliases for convenience:\n\n```python\nconvert_between_measurement_units(\n 100, \"kilometers\", \"miles\", \"length\"\n) # Works with full names\nconvert_between_measurement_units(100, \"km\", \"mi\", \"length\") # Works with abbreviations\nconvert_between_measurement_units(\n 100, \"metre\", \"yard\", \"length\"\n) # Supports alternate spellings\n```\n\n#### Auto-Detection\n\nThe system automatically figures out unit types from context:\n\n```python\nconvert_between_measurement_units(\n 100, \"kg\", \"lb\", \"mass\"\n) # Automatically detects mass conversion\n```\n\n#### Compound Units\n\nParse and handle complex compound units:\n\n```python\nparse_compound_unit(\"m/s\u00b2\") # Acceleration units\nparse_compound_unit(\"kg\u00b7m/s\u00b2\") # Force units\n```\n\n#### Scientific Notation\n\nAutomatic formatting for very large or small values:\n\n```python\nformat_scientific_notation(0.000001, precision=2) # 1.00e-6\nformat_scientific_notation(1000000, precision=2) # 1.00e+6\n```\n\n#### Conversion History\n\nTrack all conversions with timestamps:\n\n```python\nconvert_with_history(100, \"m\", \"ft\", precision=2) # Stores in history\nconversion_history.get_recent(10) # Retrieve last 10\n```\n\n### Unit Conversion Examples\n\n```python\n# Length conversions\nconvert_between_measurement_units(100, \"meters\", \"feet\", \"length\") # 328.084\nconvert_between_measurement_units(1, \"mile\", \"kilometers\", \"length\") # 1.60934\n\n# Mass conversions\nconvert_between_measurement_units(1, \"kg\", \"pounds\", \"mass\") # 2.20462\nconvert_between_measurement_units(100, \"grams\", \"ounces\", \"mass\") # 3.52740\n\n# Temperature conversions\nconvert_between_measurement_units(0, \"C\", \"F\", \"temperature\") # 32\nconvert_between_measurement_units(100, \"F\", \"C\", \"temperature\") # 37.7778\n\n# Data storage conversions\nconvert_between_measurement_units(1024, \"MB\", \"GB\", \"data\") # 1.024\nconvert_between_measurement_units(1, \"TB\", \"bytes\", \"data\") # 1099511627776\n```\n\n## Professional Financial Calculation Suite\n\nMCP Mathematics includes a complete set of financial tools designed for professional use, education, and personal money management. The financial system supports advanced calculations including compound interest modeling, loan analysis, tax calculations, and business financial work.\n\nAll financial functions use high precision to make sure you get accurate money calculations and support different compounding frequencies, payment schedules, and tax situations you'll find in real-world financial work.\n\n### Core Financial Functions\n\n#### Percentage Operations\n\n```python\ncalculate_percentage(1000, 15) # 150 (15% of 1000)\ncalculate_percentage_of(50, 200) # 25 (50 is 25% of 200)\ncalculate_percentage_change(100, 150) # 50 (50% increase)\n```\n\n#### Interest Calculations\n\n```python\n# Simple Interest\ncalculate_simple_interest(1000, 5, 10)\n# Returns: {\"interest\": 500, \"amount\": 1500}\n\n# Compound Interest\ncalculate_compound_interest(1000, 5, 10, 12) # Monthly compounding\n# Returns: {\"amount\": 1647.01, \"interest\": 647.01}\n```\n\n#### Loan Calculations\n\n```python\n# Calculate monthly payment\ncalculate_loan_payment(100000, 5, 30, 12) # $100k, 5%, 30 years, monthly\n# Returns: {\"payment\": 536.82, \"total_paid\": 193255.78, \"interest_paid\": 93255.78}\n```\n\n#### Tax Calculations\n\n```python\n# Calculate tax (inclusive or exclusive)\ncalculate_tax(100, 10, is_inclusive=False) # 10% tax on $100\n# Returns: {\"amount\": 100, \"tax\": 10, \"total\": 110}\n\ncalculate_tax(110, 10, is_inclusive=True) # Price includes 10% tax\n# Returns: {\"amount\": 100, \"tax\": 10, \"total\": 110}\n```\n\n#### Bill Operations\n\n```python\n# Split bill with tip\nsplit_bill(100, 4, tip_percent=20)\n# Returns: {\"total\": 120, \"per_person\": 30, \"tip\": 20}\n\n# Calculate tip\ncalculate_tip(100, 18) # 18% tip on $100\n# Returns: 18\n```\n\n#### Discount and Markup\n\n```python\n# Calculate discount\ncalculate_discount(100, 20) # 20% off $100\n# Returns: {\"original\": 100, \"discount\": 20, \"final\": 80}\n\n# Calculate markup\ncalculate_markup(100, 25) # 25% markup on $100 cost\n# Returns: {\"cost\": 100, \"markup\": 25, \"price\": 125}\n```\n\n## Enterprise Architecture & Security\n\nMCP Mathematics is built as an enterprise-grade mathematical computation platform that combines strong security measures with production-ready architecture. The system is designed to handle mission-critical calculations while maintaining the highest standards of code quality and security.\n\n### Multi-Layered Security Framework\n\n#### Core Security Principles\n\n- **Zero-Trust Architecture**: Every input is checked and every operation is verified\n- **Defense in Depth**: Multiple security layers give you complete protection\n- **Principle of Least Privilege**: Only essential operations are allowed\n- **Fail-Safe Defaults**: Safe defaults stop accidental security issues\n\n#### Security Implementation\n\n- **AST Evaluation Engine**: Every mathematical expression is processed through an Abstract Syntax Tree before evaluation, which stops code injection attacks while keeping full mathematical capability\n- **Operation Whitelisting**: Only specifically approved mathematical operations and functions can run, which stops unauthorized code execution\n- **Input Sanitization**: Thorough checking of all expressions and parameters before processing\n- **Error Containment**: Complete error handling makes sure calculation failures don't affect system security\n- **Dependency Minimization**: Core features need no external libraries, which greatly reduces security risks\n\n### Production-Grade Architecture\n\n#### Code Quality Standards\n\n- **Type Safety**: Complete type annotations using Python 3.10+ features make sure you catch errors at compile-time\n- **Clean Architecture**: Modular design with clear separation of concerns makes maintenance and scaling easier\n- **Professional Codebase**: Production-ready code with no debug statements, console logs, or unnecessary comments\n- **Complete Testing**: 130 unit tests give you thorough coverage across all mathematical functions and edge cases\n- **Automated Quality**: Code standards enforced through Black formatting and Ruff linting\n\n#### Performance & Reliability\n\n- **Optimized Computation**: Efficient algorithms and data structures for high-performance calculations\n- **Advanced Memory Management**: Bounded LRU and TTL cache systems with automatic cleanup stop memory leaks in long-running processes\n- **Thread-Safe Concurrency**: 100% reliable concurrent execution using Timer-based timeouts instead of signal-based approaches\n- **Session Management**: Graceful resource cleanup and session handling for enterprise environments\n- **Error Recovery**: Proper exception chaining with better traceability for debugging and monitoring\n- **Scalability**: Architecture designed to handle high-volume calculation workloads with concurrent processing\n\n## Development Guide\n\nThis complete guide gives you everything you need to contribute to MCP Mathematics, from setting up your development environment to building production-ready distributions. The project follows strict quality standards and automated workflows to make sure everything works reliably and stays maintainable.\n\n### Development Environment Setup\n\n#### Prerequisites\n\n```bash\n# Ensure Python 3.10+ is installed\npython --version # Should be 3.10 or higher\n\n# Clone the repository\ngit clone https://github.com/SHSharkar/MCP-Mathematics.git\ncd MCP-Mathematics\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Install development dependencies\npip install -e \".[dev]\"\n```\n\n### Quality Assurance Workflow\n\n#### Running the Complete Test Suite\n\nRun the comprehensive test suite covering all 130 test cases:\n\n```bash\n# Run all tests with detailed output\npython -m pytest tests/ -v\n\n# Run tests with coverage reporting\npython -m pytest tests/ --cov=src --cov-report=html\n\n# Run specific test categories\npython -m pytest tests/test_calculator.py -v # Core functionality\npython -m pytest tests/test_unit_conversion.py -v # Unit conversions\npython -m pytest tests/test_financial.py -v # Financial calculations\n```\n\n#### Code Quality and Standards\n\nKeep professional code standards with automated quality tools:\n\n```bash\n# Auto-format code with Black (100-character line limit)\nblack src/ tests/ --line-length 100\n\n# Comprehensive linting with Ruff\nruff check src/ tests/ --fix\n\n# Type checking with mypy\nmypy src/\n\n# Run complete pre-commit validation\npre-commit run --all-files\n```\n\n#### Performance and Security Validation\n\n```bash\n# Security analysis\nbandit -r src/\n\n# Performance profiling for mathematical operations\npython -m cProfile -s cumtime scripts/benchmark.py\n\n# Memory usage analysis\npython -m memory_profiler scripts/memory_test.py\n```\n\n### Distribution and Deployment\n\n#### Building Production Packages\n\nCreate optimized distribution packages for PyPI:\n\n```bash\n# Install build tools\npip install build twine\n\n# Clean previous builds\nrm -rf dist/ build/\n\n# Build source and wheel distributions\npython -m build\n\n# Verify package integrity\ntwine check dist/*\n\n# Test installation in clean environment\npip install dist/*.whl\n```\n\n#### Release Management\n\n```bash\n# Tag release version\ngit tag -a v1.0.0 -m \"Release version 1.0.0\"\n\n# Push tags to trigger CI/CD\ngit push origin --tags\n\n# Upload to PyPI (maintainers only)\ntwine upload dist/*\n```\n\n## Error Handling\n\nMCP Mathematics gives you clear, helpful error messages to help you figure out what went wrong:\n\n- **Syntax Errors**: Clear identification of malformed expressions\n- **Division by Zero**: Smooth handling of mathematical impossibilities\n- **Invalid Functions**: Helpful messages when unknown functions are called\n- **Type Errors**: Detailed information about incompatible operations\n- **Empty Expressions**: Helpful feedback when input is missing\n\n## System Requirements\n\n- Python 3.10 or higher\n- MCP SDK 1.4.1 or later\n\n## License\n\nMCP Mathematics is released under the MIT License. Copyright \u00a9 2025 Md. Sazzad Hossain Sharkar\n\n## Author\n\n**Md. Sazzad Hossain Sharkar**\nGitHub: [@SHSharkar](https://github.com/SHSharkar)\nEmail: md@szd.sh\n\n## Contributing\n\nWe welcome contributions that maintain our high standards for code quality. When you contribute:\n\n- Write clean, comment-free production code\n- Include complete type annotations\n- Add complete test coverage for new features\n- Keep a clean, logical git history\n\n## Acknowledgments\n\nMCP Mathematics is built on the Model Context Protocol (MCP) specification developed by Anthropic, extending it with production-ready mathematical capabilities designed for professional use.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Production-ready MCP server built with FastMCP v2 for comprehensive mathematical operations, providing 52 advanced functions, 158 unit conversions, and enterprise-grade security",
"version": "2.3.1",
"project_urls": {
"Documentation": "https://github.com/SHSharkar/MCP-Mathematics#readme",
"Homepage": "https://github.com/SHSharkar/MCP-Mathematics",
"Issues": "https://github.com/SHSharkar/MCP-Mathematics/issues",
"Repository": "https://github.com/SHSharkar/MCP-Mathematics",
"Source": "https://github.com/SHSharkar/MCP-Mathematics"
},
"split_keywords": [
"ai",
" api",
" assistant",
" calculator",
" chatgpt",
" claude",
" computation",
" converter",
" finance",
" formula",
" gpt",
" llm",
" math",
" mathematics",
" mcp",
" python",
" scientific",
" solver",
" tool",
" unit-conversion"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "324cec86e4153ce98977444847a4bef70f4d057818d64e3be4db60c01c57f353",
"md5": "3079ea9c722199cb700bdc3df0fe2e52",
"sha256": "24dda587315516307c19c81ddecce6c5d612e14c1b08ec61583dbc73304a4f5c"
},
"downloads": -1,
"filename": "mcp_mathematics-2.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3079ea9c722199cb700bdc3df0fe2e52",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 33321,
"upload_time": "2025-10-18T08:11:53",
"upload_time_iso_8601": "2025-10-18T08:11:53.671680Z",
"url": "https://files.pythonhosted.org/packages/32/4c/ec86e4153ce98977444847a4bef70f4d057818d64e3be4db60c01c57f353/mcp_mathematics-2.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "96cc34d4197e9dfc0982c0df9e38989af1d6b4709b1de964805614d474944092",
"md5": "4c187fa2f417ee288877fd5cc095e2c5",
"sha256": "d57f4387ab76890ea3762448ed4e8a91f12a90704c69f863be5fbc101ab121d3"
},
"downloads": -1,
"filename": "mcp_mathematics-2.3.1.tar.gz",
"has_sig": false,
"md5_digest": "4c187fa2f417ee288877fd5cc095e2c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 136280,
"upload_time": "2025-10-18T08:11:56",
"upload_time_iso_8601": "2025-10-18T08:11:56.509714Z",
"url": "https://files.pythonhosted.org/packages/96/cc/34d4197e9dfc0982c0df9e38989af1d6b4709b1de964805614d474944092/mcp_mathematics-2.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-18 08:11:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SHSharkar",
"github_project": "MCP-Mathematics#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mcp-mathematics"
}
JSON
