npm package: @neural-symphony/pysr-mcp-server
Description: MCP server for PySR (Python Symbolic Regression) - discover symbolic mathematical expressions from data
Author: neural-symphony
Latest version: 0.1.0

# PySR MCP Server

An MCP (Model Context Protocol) server that provides symbolic regression capabilities through [PySR](https://github.com/MilesCranmer/PySR) to Claude Code and other MCP clients.

## Overview

This server enables AI assistants to discover symbolic mathematical expressions that fit data using evolutionary algorithms. PySR searches through the space of possible equations to find interpretable formulas that optimize a given objective.

## Features

The server exposes four main tools:

- **fit_symbolic_regression**: Train a model to discover symbolic expressions
- **get_equations**: Retrieve all discovered equations with metrics
- **predict**: Make predictions using trained models
- **export_equation**: Export equations to LaTeX, SymPy, PyTorch, or JAX format

## Prerequisites

- **Node.js** >= 18.0.0
- **Python** >= 3.8
- **PySR** installed in your Python environment

### Installing PySR

```bash
pip install pysr
```

PySR will automatically install Julia dependencies on first import.

## Installation

### Quick Install (npm)

Install with a single command using npx:

```bash
claude mcp add pysr npx @pysr/mcp-server
```

**Important**: Restart Claude Code after installation for the tools to become available.

### Custom Python Path

If PySR is in a specific Python environment:

```bash
claude mcp add pysr --env PYTHON_PATH=/path/to/python -- npx @pysr/mcp-server
```

### Local Development Install

For development or testing from source:

```bash
# Clone or download the repository
cd pysr-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Add to Claude Code
claude mcp add pysr-mcp node /absolute/path/to/pysr-mcp-server/dist/index.js
```

### Verification

After installation and restarting Claude Code, verify the tools are available:

```bash
claude mcp list
```

You should see `pysr` or `pysr-mcp` in the list of active MCP servers.

## Usage Examples

### Example 1: Fit a simple equation

```python
# Sample data: y = 2.5 * cos(x0) + x1^2 - 0.5
X = [[1.2, 0.5], [2.1, 1.3], [0.8, 2.1], ...]
y = [1.83, 3.45, 2.11, ...]
```

Use the `fit_symbolic_regression` tool with:
- **X**: Your feature matrix (2D array)
- **y**: Your target values (1D array)
- **niterations**: Number of training iterations (e.g., 40)
- **binary_operators**: Operations like `["+", "*", "-", "/"]`
- **unary_operators**: Functions like `["cos", "exp", "sin"]`

The tool returns a `model_path` that you can use with other tools.

### Example 2: Get discovered equations

Use `get_equations` with the `model_path` from training to see all discovered formulas ranked by accuracy and complexity.

### Example 3: Make predictions

Use `predict` with:
- **model_path**: From your trained model
- **X**: New data for prediction
- **equation_index** (optional): Specify which equation to use

### Example 4: Export equations

Use `export_equation` to get equations in different formats:
- **latex**: For documentation
- **sympy**: For symbolic manipulation in Python
- **torch**: For differentiable PyTorch models
- **jax**: For JAX/Flax integration

## Configuration

### Environment Variables

- **PYTHON_PATH**: Path to Python executable (default: `python`)
- **PYSR_PYTHON**: Alternative way to specify Python path

### Custom Python Environment

If PySR is installed in a specific environment:

```bash
claude mcp add pysr-mcp --env PYTHON_PATH=/path/to/conda/envs/pysr/bin/python -- node /path/to/dist/index.js
```

## Architecture

```
┌─────────────┐
│ Claude Code │
└──────┬──────┘
       │ MCP Protocol (stdio)
       │
┌──────▼───────────────┐
│  MCP Server (Node)   │
│  - index.ts          │
│  - tools.ts          │
│  - pysr-wrapper.ts   │
└──────┬───────────────┘
       │ Python subprocess
       │
┌──────▼──────┐
│    PySR     │
│   (Python)  │
└─────────────┘
```

## Tool Specifications

### fit_symbolic_regression

**Input:**
- `X` (required): 2D array of features
- `y` (required): 1D array of targets
- `niterations` (optional): Training iterations (default: 40)
- `populations` (optional): Number of populations (default: 8)
- `population_size` (optional): Size per population (default: 50)
- `binary_operators` (optional): List of binary ops (default: `["+", "*", "-", "/"]`)
- `unary_operators` (optional): List of unary ops (default: `["cos", "exp", "sin"]`)
- `maxsize` (optional): Max equation complexity (default: 20)
- `maxdepth` (optional): Max tree depth (default: 10)
- `timeout_in_seconds` (optional): Max training time (default: 300)

**Output:** Model path and training summary

### get_equations

**Input:**
- `model_path` (required): Path to saved model

**Output:** Array of equations with metrics (score, complexity, loss, etc.)

### predict

**Input:**
- `model_path` (required): Path to saved model
- `X` (required): 2D array for prediction
- `equation_index` (optional): Specific equation index

**Output:** Prediction array

### export_equation

**Input:**
- `model_path` (required): Path to saved model
- `format` (required): One of `"latex"`, `"sympy"`, `"torch"`, `"jax"`
- `equation_index` (optional): Specific equation index

**Output:** Equation in requested format

## Troubleshooting

### "Python not found"
Make sure Python is in your PATH or set `PYTHON_PATH` environment variable.

### "PySR not installed"
Install PySR: `pip install pysr`

### "Julia dependencies missing"
PySR auto-installs Julia dependencies on first import. Run `python -c "import pysr"` manually to trigger installation.

### Long training times
Symbolic regression can be computationally intensive. Consider:
- Reducing `niterations`
- Setting `timeout_in_seconds`
- Using simpler operator sets
- Reducing `maxsize` and `maxdepth`

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch
```

## License

MIT

## Related Links

- [PySR Documentation](https://ai.damtp.cam.ac.uk/pysr/)
- [PySR Paper](https://arxiv.org/abs/2305.01582)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Code](https://docs.claude.com/claude-code)