Content
# octave-mcp
MCP(Model Context Protocol) server that connects GNU Octave with Claude AI.
You can execute Octave code in natural language with Claude Code, and perform numerical calculations, graph plotting, image processing, and deep learning inference directly.
## Features
- Execute Octave code with MCP tool (`run_octave`)
- Return text results (stdout/stderr) to Claude
- Automatically save graph commands (e.g., `plot`, `imagesc`, `surf`) as PNG files and return as images
- Integrate external libraries (e.g., PyTorch/torchvision) using Python (`system()` call)
## Requirements
| Item | Version |
|------|------|
| Node.js | 18 or higher |
| GNU Octave | 6.0 or higher |
| Python | 3.9 or higher (for deep learning features) |
### Optional Python dependencies (for deep learning features)
```
torch >= 2.0
torchvision >= 0.15
scikit-image >= 0.20
scipy >= 1.10
pooch # required for loading scipy.datasets images
Pillow
```
## Installation
```bash
git clone <repo-url>
cd octave-mcp
npm install
```
## Registering Claude Code MCP
Add the following content to `~/.claude/claude_desktop_config.json` (or MCP settings file):
```json
{
"mcpServers": {
"octave": {
"command": "node",
"args": ["/Users/<yourname>/octave-mcp/index.js"]
}
}
}
```
## Usage
Simply request in natural language in the Claude Code chat window:
```
Calculate the sum of 1 to 10 using Octave
Plot a sin graph using Octave
Perform 2D Fourier transform and display the spectrum
Infer a raccoon image using ResNet18
```
## Server Structure
```
octave-mcp/
├── index.js # MCP server entry point
├── package.json
├── resnet18_raccoon_result.png # ResNet18 inference result image
├── outputs/ # directory for generated graphs and images
│ ├── plot_<uuid>.png
│ └── resnet18_raccoon_result.png
└── README.md
```
### Workflow
1. Claude → MCP `run_octave` tool call (Octave code delivery)
2. `index.js` creates an `octave --no-gui --eval <code>` process
3. Automatically inserts `print(gcf, '<path>', '-dpng', '-r150')` when detecting graph commands
4. Returns stdout / generated PNG to Claude
## Example Use Cases
### Numerical Calculation
```octave
result = sum(1:10);
printf('Sum: %d\n', result);
% -> 55
```
### 2D Fourier Transform & Inverse Transform
```octave
img = peaks(256);
F = fft2(img);
F_shifted = fftshift(F);
img_rec = real(ifft2(ifftshift(F_shifted)));
% Reconstruction error: ~1e-13 (floating-point level)
```
### ResNet18 Image Classification (Python integration)
```octave
[status, out] = system('python3 /tmp/resnet_infer.py 2>&1');
% Top1: badger 35.59% / Top2: grey fox 17.83% ...
```
## Inference Result Example
| Rank | Class | Probability |
|------|--------|------|
| Top1 | badger | 35.59% |
| Top2 | grey fox | 17.83% |
| Top3 | lesser panda | 8.63% |
| Top4 | three-toed sloth | 7.69% |
| Top5 | Madagascar cat | 2.45% |
> Note that the ImageNet-1K dataset does not have a raccoon class, so it is classified as a similar animal (badger).
## Output Files
Graphs and inference result images are saved in `~/octave-mcp/outputs/`.
| File | Content |
|------|------|
| `plot_<uuid>.png` | Octave graph output |
| `resnet18_raccoon_result.png` | ResNet18 inference result overlay image |
## Known Limitations
- Some commands (e.g., `imshow`) are not included in the plot detection pattern and require separate loading using `imread`.
- Octave execution timeout default: **30 seconds**
- `skimage.data.raccoon()` is removed in scikit-image v0.20 → use `scipy.datasets.face()`
- No raccoon class in ImageNet-1K → ResNet18 classifies as similar animals (e.g., badger)
## License
ISC
