SimBiology MCP Server

Overview

The SimBiology MCP Server is a Model Context Protocol (MCP) interface for MATLAB SimBiology, enabling programmatic control of biological modeling and simulation workflows from AI agents and external tools.

It bridges large language model systems with MATLAB's SimBiology toolbox through the MATLAB Engine for Python, allowing automated creation, modification, and execution of computational biology models.

Purpose

SimBiology is a powerful environment for modeling biochemical and pharmacokinetic systems, but it is primarily MATLAB-driven and interactive.

This MCP server provides a structured programmatic layer that:

• Exposes SimBiology functionality as MCP tools
• Enables automated model construction and simulation
• Supports agent-driven workflows for systems biology
• Removes the need for manual MATLAB interaction
• Supports workflows such as building PK/PD models, modifying reactions and parameters, simulating time courses, exporting results, and pulling supporting context from PubMed (including open-access full text), the iGEM registry, and SABIO-RK reaction kinetics

Installation

Choose one way to install the Python package, then complete the common setup steps below.

1. Manual repo checkout

Use this when you want the full source tree locally, including the repo skill files and tests.

git clone https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP.git
cd SIMBIOLOGY-MCP
python -m venv .venv

Activate the virtual environment:

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS or Linux
source .venv/bin/activate

python -m pip install -e .

2. Recommended: uv tool install

Use this when you want a cleaner install without cloning the repo.

uv tool install simbiology-mcp

3. Plain pip

Use this if you do not want uv tool install.

python -m pip install simbiology-mcp

Complete the setup

The easiest option is the interactive setup. It installs the MATLAB Engine, configures an MCP client, and offers to install the matching skill:

simbiology-mcp setup

For a fully interactive setup, follow the prompts to choose your MATLAB installation, client, configuration scope, and skill destination.

For headless or engine-only setup, install the MATLAB Engine for Python from your local MATLAB installation:

simbiology-mcp setup --skip-configure

If multiple MATLAB installations are found, select one interactively or pass an index:

simbiology-mcp setup --matlab-index 0 --skip-configure

Configure an MCP client:

simbiology-mcp configure --client cursor
simbiology-mcp configure --client codex --project
simbiology-mcp configure --list-clients

The configuration helper supports Claude Code, Cursor, Codex, Windsurf, GitHub Copilot CLI, and Visual Studio Code/GitHub Copilot. The user scope is the default; use --project for project-local configuration. Existing matching entries are left unchanged; use --force to replace a different existing entry.

Install the synthetic biology modelling skill separately:

simbiology-mcp get-skill --client codex

Use --client, --project, --user, or --install-path to choose a destination directly. Run simbiology-mcp get-skill without flags for the interactive picker.

Add --no-skill to omit the skill installation.

Requirements

• MATLAB R2024a or later
• SimBiology Toolbox installed
• Python 3.12 or later
• A MATLAB-supported Windows, macOS, or Linux environment
• An MCP-compatible client; the configuration helper supports Claude Code, Cursor, Codex, Windsurf, GitHub Copilot CLI, and Visual Studio Code/GitHub Copilot

Usage

Once setup has configured the MCP server for your chosen agent, launch or restart that agent's client session. The client starts the server automatically when it connects to it; you do not need to run start manually.

Manual configuration and server start

Use manual configuration only when your client is not supported by configure:

Point your MCP client at the installed server executable. Use the absolute path so the client does not depend on your shell's PATH:

{
  "mcpServers": {
    "simbiology": {
      "command": "C:/absolute/path/to/simbiology-mcp.exe",
      "args": ["start"]
    }
  }
}

Alternatively, run the server directly from an activated repository environment:

python -m simbiology_mcp start

The MATLAB engine starts lazily on the first tool call that needs it, so client startup stays fast.

External API keys

PubMed works without a key but is rate-limited. To raise the limit, copy .env.example to .env and set NCBI_API_KEY.

The iGEM registry and the SABIO-RK kinetics database are queried without any key.

Tools

The server exposes the following MCP tools:

Project layout

simbiology_mcp/
├── core/        SimBiology session, per-model reads, and command builders
├── engine/      Singleton MATLAB engine wrapper and error types
├── tools/       MCP tool definitions and the shared registry
├── external/    PubMed, iGEM, and SABIO-RK API wrappers
├── interfaces/  FastMCP server wiring
├── scripts/     CLI helpers like setup, configure, and get-skill
└── skills/      Packaged skill markdown
examples/        Runnable demos (e.g. demo_simulation.py)
tests/           Unit tests plus MATLAB/live integration tests

Authors

• Yojith Sai Biradavolu
• Sepanta Yalameha

Contributions, issues, and feature requests are welcome through the project’s GitHub repository.

Development

Run the hermetic test suite (no MATLAB or network required):

py -m pytest -m "not matlab and not live"

matlab tests require a working MATLAB Engine install. live tests hit external APIs and run only with --run-live.