math-mcp-learning-server
Educational MCP server with 17 tools, persistent workspace, and cloud hosting. Built with FastMCP and the official Model Context Protocol Python SDK.
Available on the MCP Registry (io.github.clouatre-labs/math-mcp-learning-server) and PyPI.
## Demo
See [CONTRIBUTING.md](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/CONTRIBUTING.md#demo-gif) for instructions to record your own demo.
## Quick Start
### Cloud (No Installation)
Connect your MCP client to the hosted server:
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"math-cloud": {
"transport": "http",
"url": "https://math-mcp.fastmcp.app/mcp"
}
}
}
```
### Local Installation
```json
{
"mcpServers": {
"math": {
"command": "uvx",
"args": ["math-mcp-learning-server[scientific,plotting]"]
}
}
}
```
For other installation options (basic, scientific-only, plotting-only), see [CONTRIBUTING.md](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/CONTRIBUTING.md).
## Tools
| Category | Tool | Description |
|----------|------|-------------|
| **Workspace** | `workspace_save` | Save calculations to persistent storage |
| | `workspace_load` | Retrieve previously saved calculations |
| **Math** | `calc_expression` | Safely evaluate mathematical expressions |
| | `calc_statistics` | Statistical analysis (mean, median, mode, std_dev, variance) |
| | `calc_interest` | Calculate compound interest for investments |
| | `calc_units` | Convert between units (length, weight, temperature) |
| **Matrix** | `matrix_multiply` | Multiply two matrices |
| | `matrix_transpose` | Transpose a matrix |
| | `matrix_determinant` | Calculate matrix determinant |
| | `matrix_inverse` | Calculate matrix inverse |
| | `matrix_eigenvalues` | Calculate eigenvalues |
| **Visualization** | `plot_function` | Plot mathematical functions |
| | `plot_histogram` | Create statistical histograms |
| | `plot_line_chart` | Create line charts |
| | `plot_scatter` | Create scatter plots |
| | `plot_box_plot` | Create box plots |
| | `plot_financial_line` | Create financial line charts |
## Resources
- `math://workspace` - Persistent calculation workspace summary
- `math://history` - Chronological calculation history
- `math://functions` - Available mathematical functions reference
- `math://constants/{constant}` - Mathematical constants (pi, e, golden_ratio, etc.)
- `math://catalog/tools` - Tool catalog with metadata and usage examples
- `math://variables` - Active variables in the current workspace
- `math://test` - Server health check
## Prompts
- `math_tutor` - Structured tutoring prompts (configurable difficulty)
- `formula_explainer` - Formula explanation with step-by-step breakdowns
See [Usage Examples](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/docs/EXAMPLES.md) for detailed examples.
## Development
See [CONTRIBUTING.md](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/CONTRIBUTING.md) for development setup, testing, and contribution guidelines.
## Security
- **OpenSSF Best Practices Silver** - Fewer than 1% of open source projects reach this level
- **REUSE/SPDX** - License compliance for all files
- **Signed Commits** - GPG-signed commits required
- **Dependency Scanning** - Automated updates via Renovate
- **pip-audit CVE Scanning** - Automated dependency vulnerability checks
- **gitleaks Secret Scanning** - Detects secrets in code and history
- **zizmor GitHub Actions Security** - Workflow security scanning
- **commitlint Enforcement** - Conventional commit validation in CI
- **OpenSSF Scorecard** - Continuous open source security assessment
calc_expression safety
The `calc_expression` tool uses restricted `eval()` with a whitelist of allowed characters and functions, restricted global scope (only `math` module and `abs`), and no access to dangerous built-ins or imports. All tool inputs are validated with Pydantic models. File operations are restricted to the designated workspace directory. Complete type hints and validation are enforced for all operations.
## Documentation
- [Architecture](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/docs/ARCHITECTURE.md)
- [Cloud Deployment Guide](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/docs/CLOUD_DEPLOYMENT.md)
- [Usage Examples](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/docs/EXAMPLES.md)
- [Contributing Guidelines](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/CONTRIBUTING.md)
- [Maintainer Guide](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/.github/MAINTAINER_GUIDE.md)
- [Roadmap](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/ROADMAP.md)
- [Code of Conduct](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/CODE_OF_CONDUCT.md)
- [License](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/LICENSE)