Content
# SciCompute MCP Server
MCP server for scientific computing with multiple backends. Provides AI coding assistants with mathematical computation and visualization capabilities.
## Features
- Multiple computing backends (Mathematica, Octave, Python Scientific, R, SageMath)
- Image output support (plots, graphics)
- Automatic backend selection
- Persistent session state (variables persist across calls)
- Documentation query for unknown symbols
- Multi-platform support (Claude Code, Claude Desktop, OpenCode/Crush)
- **Recommended**: Use alongside [official MATLAB MCP Server](https://github.com/matlab/matlab-mcp-core-server) for MATLAB support
## Supported Backends
| Backend | Status | Capabilities |
|---------|--------|--------------|
| Mathematica | ✅ Ready | symbolic, numeric, plot, image, audio |
| SageMath | ✅ Ready | symbolic, numeric, plot |
| Python Scientific | ✅ Ready | symbolic, numeric, plot |
| R | ✅ Ready | numeric, plot |
| Octave | ✅ Ready | numeric, plot |
| Julia | ✅ Ready | numeric, plot |
| Maxima | ✅ Ready | symbolic, numeric, plot |
### MATLAB Support
For **MATLAB** support, we recommend using the official [MATLAB MCP Core Server](https://github.com/matlab/matlab-mcp-core-server) from MathWorks alongside SciCompute:
**Why use the official server?**
- No Python version restrictions (works with any Python version)
- No library installation or patching required
- Standalone Go binary with no dependencies
- Additional features: code analysis, test running, toolbox detection
**Installation:**
1. Download the MATLAB MCP Core Server binary from the [latest release](https://github.com/matlab/matlab-mcp-core-server/releases/latest):
```bash
# Linux x86_64
curl -L -o ~/matlab-mcp-core-server https://github.com/matlab/matlab-mcp-core-server/releases/latest/download/matlab-mcp-core-server-glnxa64
chmod +x ~/matlab-mcp-core-server
```
2. Configure both servers in your MCP config:
```json
{
"mcpServers": {
"scicompute": {
"command": "uvx",
"args": ["scicompute-mcp"]
},
"matlab": {
"command": "/home/username/matlab-mcp-core-server",
"args": ["--matlab-root=/usr/local/MATLAB/R2024a"]
}
}
}
```
See the [MATLAB MCP Core Server documentation](https://github.com/matlab/matlab-mcp-core-server) for more details.
## Installation
> **Tip**: Ask your AI assistant to install it for you! Just say "Install scicompute-mcp" and it will handle everything automatically.
### Quick Start (Recommended)
```bash
# Install and run with uvx (auto-manages environment)
uvx scicompute-mcp
# Or install with pip
pip install scicompute-mcp
scicompute-mcp
```
### Debian 12+ / Ubuntu 23.04+
These systems enable PEP 668 by default, which prevents direct pip installs. Use one of these methods:
```bash
# Method 1: Use --break-system-packages (quick)
pip install --break-system-packages scicompute-mcp
# Method 2: Use pipx (recommended for CLI tools)
sudo apt install -y pipx
pipx install scicompute-mcp
# Method 3: Use China mirror (faster in China)
pip install --break-system-packages -i https://pypi.tuna.tsinghua.edu.cn/simple scicompute-mcp
```
After installation, add `~/.local/bin` to PATH if needed:
```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
### Install with Optional Backends
```bash
# With Mathematica support
pip install scicompute-mcp[mathematica]
# With Octave support
pip install scicompute-mcp[octave]
# With all backends
pip install scicompute-mcp[all]
```
### Environment Architecture
```
┌───────────────────────────────────────────────────────────────────────────┐
│ MCP Server (Python 3.10+) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────────────┐ │
│ │ Mathematica │ │ Octave │ │ MATLAB │ │ py_scientific │ │
│ │ Backend │ │ Backend │ │ Backend │ │ (same Python env) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Wolfram │ │ octave │ │ MATLAB │ │ R │ sage │
│ │ Kernel │ │ process │ │ process │ │ process │ process │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ Independent Independent Independent Independent conda │
│ (official) (apt/brew) (official) (apt/brew) env │
└───────────────────────────────────────────────────────────────────────────┘
```
**Key Points**:
- MCP server only needs **one** Python environment
- Each backend (except py_scientific) runs as independent process, not sharing Python environment
- SageMath requires separate conda environment (Python < 3.13)
### Step 1: Install Computing Backends
Install the computing backends you need (not all required):
#### Python Scientific Backend
Pre-installed with the main package, no additional configuration needed.
#### SageMath Backend
SageMath requires Python < 3.13, must be installed separately via conda:
```bash
# Configure mirror (optional, recommended for users in China)
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
# Create SageMath environment
conda create -n sage python=3.11 -y
conda install -n sage -c conda-forge sage -y
```
Configure path (choose one):
```bash
# Method A: Environment variable (recommended)
export SAGE_PATH="$HOME/miniconda3/envs/sage/bin/sage"
# Method B: Modify SAGE_PATH in code
# Edit src/scicompute_mcp/backends/sage.py
```
#### R Backend
```bash
# Ubuntu/Debian
sudo apt install r-base
# macOS
brew install r
# Windows: Download from CRAN
```
#### Octave Backend
```bash
# Ubuntu/Debian
sudo apt install octave gnuplot
# macOS
brew install octave gnuplot
# Windows: Download Octave installer
```
#### Julia Backend
```bash
# Install Julia (recommended: use juliaup)
curl -fsSL https://install.julialang.org | sh
# Or download from https://julialang.org/downloads/
# Install Python package
pip install juliacall
```
#### Mathematica Backend
1. Purchase and install from [Wolfram website](https://www.wolfram.com/mathematica/)
2. Configure path:
```bash
export MATHEMATICA_KERNEL_PATH="/usr/local/Wolfram/Wolfram/14.3/Executables/WolframKernel"
```
## Configuration
### Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `SAGE_PATH` | SageMath path | `$HOME/miniconda3/envs/sage/bin/sage` |
| `MATHEMATICA_KERNEL_PATH` | WolframKernel path | `/usr/local/Wolfram/Wolfram/14.3/Executables/WolframKernel` |
| `JULIA_PATH` | Julia executable path | `$HOME/.juliaup/bin/julia` |
| `SCICOMPUTE_PRIORITY` | Backend priority | `mathematica,sage,julia,py_scientific` |
### Claude Code (`.mcp.json`)
```json
{
"mcpServers": {
"scicompute": {
"command": "uvx",
"args": ["scicompute-mcp"]
}
}
}
```
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"scicompute": {
"command": "uvx",
"args": ["scicompute-mcp"]
}
}
}
```
### OpenCode / Crush
#### OpenCode 1.4.6+
OpenCode 1.4.6+ reads configuration from `~/.config/opencode/opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"scicompute": {
"type": "local",
"command": ["/home/username/.local/bin/scicompute-mcp"]
}
}
}
```
> **Important**: Use absolute path to `scicompute-mcp` (from `pip install`). Avoid `uvx` because it downloads dependencies on first run, which may timeout.
To verify:
```bash
opencode mcp list
```
#### Using `opencode mcp add` (Interactive)
Alternatively, add via interactive command:
```bash
opencode mcp add
# Name: scicompute
# Type: Local
# Command: /home/username/.local/bin/scicompute-mcp
```
#### Older OpenCode versions
For older versions, use `~/.opencode.json`:
```json
{
"mcpServers": {
"scicompute": {
"type": "stdio",
"command": "/home/username/.local/bin/scicompute-mcp"
}
}
}
```
### Local Development
For development or if you want to use a local installation:
```json
{
"mcpServers": {
"scicompute": {
"command": "/path/to/.venv/bin/python",
"args": ["-m", "scicompute_mcp.server"]
}
}
}
```
## Multi-Platform Support
This project supports multiple AI assistant platforms. Configuration templates are provided in the `configs/` directory:
| File | Platform |
|------|----------|
| `configs/claude-code.json` | Claude Code |
| `configs/claude-desktop.json` | Claude Desktop |
| `configs/opencode.json` | OpenCode / Crush |
### Custom Prompts / Skills
Each platform has its own way to provide custom instructions:
| Platform | Directory | Format |
|----------|-----------|--------|
| Claude Code | `.claude/skills/*.md` | Markdown |
| OpenCode / Crush | `.opencode/commands/*.md` | Markdown |
Users can create custom skill files if needed.
## Tools
### Calling Convention
Different MCP clients have different naming conventions for calling tools:
| Client | Format | Example |
|--------|--------|---------|
| Claude Code | `mcp__{server}__{tool}` | `mcp__scicompute__compute(code="1+1")` |
| OpenCode | `{server}_{tool}` | `scicompute_compute(code="1+1")` |
The examples below use the base tool names (`compute`, `list_backends`, `stop`). Your AI assistant will automatically use the correct format for its client.
### compute(code, backend?)
Execute scientific computing code.
```python
# Plot with Octave
compute("x = 0:0.1:10; y = sin(x); plot(x, y)", "octave")
# Symbolic computation with SageMath
compute("integrate(sin(x), x)", "sage")
compute("diff(x^3 * exp(x), x)", "sage")
# Mathematica
compute("Plot[Sin[x], {x, 0, 2 Pi}]", "mathematica")
compute("Integrate[x^2, x]", "mathematica")
# R Statistics
compute("mean(rnorm(1000))", "r")
compute("hist(rnorm(1000))", "r")
# Python Scientific
compute("sp.integrate(sp.sin(sp.Symbol('x')), sp.Symbol('x'))", "py_scientific")
# Julia
compute("plot(rand(10))", "julia")
compute("sqrt(2.0)", "julia")
# MATLAB
compute("plot(1:10, rand(1,10))", "matlab")
compute("[V,D] = eig(magic(3))", "matlab")
```
### list_backends()
List all available backends and their capabilities.
### stop(backend?)
Stop backend process and clear all state. Useful to reset variables or free memory.
```python
stop() # List running backends (does NOT stop any)
stop("octave") # Stop specific backend
stop("ALL") # Stop all running backends
```
**Safety design**: Calling `stop()` without arguments will NOT stop any backends. It returns a list of running backends. This prevents accidental data loss.
### doc(backend?, symbol?)
Get documentation URLs for computing backends. Use this to find where to look up function documentation.
```python
# List all backends with documentation
doc()
# Get URLs for a specific backend
doc(backend="mathematica")
doc(backend="numpy")
# Get URL for a specific function
doc(backend="mathematica", symbol="Plot3D")
doc(backend="octave", symbol="linspace")
```
**Supported backends**: mathematica, numpy, scipy, matplotlib, sympy, pandas, python, r, julia, octave, sage, maxima, matlab
## Usage Examples
Ask your AI assistant:
```
Plot sin(x) from 0 to 2π
Calculate ∫x²dx from 0 to 1
Solve x² - 4 = 0
Look up NDSolve documentation
```
## Getting Documentation
When you need detailed documentation for a function:
1. Use the `doc` tool to get documentation URLs
2. Launch a subagent with Task tool to fetch and extract documentation
3. Supported backends: Mathematica, NumPy, SciPy, Matplotlib, SymPy, Pandas, R, Julia, Octave, SageMath, Maxima, MATLAB
Example:
```
# Get documentation URL
doc(backend="mathematica", symbol="Plot3D")
# Then fetch the documentation
Task(
description="Fetch Plot3D docs",
prompt="Fetch Mathematica documentation for Plot3D from the URL returned by doc tool",
subagent_type="general"
)
```
## Documentation
- `docs/sage.md` - SageMath collaboration guide
- `docs/r.md` - R collaboration guide
- `docs/maxima.md` - Maxima collaboration guide
- `docs/octave.md` - Octave collaboration guide
- Use `doc()` tool for documentation URLs
## Requirements
- Miniconda (recommended) or Python 3.10+
- For SageMath backend: conda environment with Python 3.11
- For R backend: R installation
- For Octave backend: GNU Octave + gnuplot
- For Mathematica backend: Wolfram Mathematica
- For MATLAB backend: MATLAB + MATLAB Engine for Python
## License
Unlicense - Public Domain
