Xcos MCP
Xcos MCP is a generic Model Context Protocol server for controlling a local Scilab/Xcos installation, from block discovery and model authoring to validation and numerical simulation.
Check MCP responsiveness and Scilab/Xcos runtime paths, version, and headless support (
ping,get_xcos_runtime).Discover installed Xcos block interfaces and read their Scilab source (
list_xcos_blocks,get_xcos_block_source).Create native one-block Xcos templates exported by real Xcos (
create_xcos_block_template).Inspect saved models for blocks, links, duration, and
TOWS_coutputs (inspect_xcos_model).Structurally check and atomically save Xcos XML inside allowed roots, preserving diagram geometry by default (
save_xcos_model).Validate/import diagrams with real Scilab/Xcos (
validate_xcos_model).Simulate diagrams for arbitrary positive durations and return named
TOWS_cseries inline or as persisted artifacts (simulate_xcos_model).Read selected signals and bounded time windows from persisted simulation artifacts (
read_xcos_simulation_artifact).Reformat simple diagrams into left-to-right signal lanes without changing equations when safe (
layout_xcos_model).Run a real first-order model example and return its numerical response (
simulate_first_order_model).Calculate step-response metrics such as rise, settling, overshoot, error, and optional control effort (
analyze_step_response).
Controls a local Scilab/Xcos installation, enabling discovery of the installed block library, creation of native block templates, reading/writing/validating Xcos diagrams, and running simulations of arbitrary durations that return named numerical signal series.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Xcos MCP run the spacecraft Xcos model for 12,000 seconds and give me the signal series"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Xcos MCP
Xcos MCP is a generic Model Context Protocol server for controlling a local Scilab/Xcos installation. It discovers the installed block library, creates native templates, reads and writes diagrams, validates them with Xcos, runs simulations for arbitrary positive durations, and returns numerical signals.
MCP client -> xcos-mcp -> Scilab/Xcos -> scicos_simulate -> TOWS_c dataThe server contains no satellite-specific tools or dynamics. Control examples and optional space-dynamics examples are ordinary Xcos clients of the same API.
Requirements
Python 3.10 or newer
Scilab with Xcos
xvfb-runon headless Linux systems
The full scilab executable is required for Xcos operations. scilab-cli is
used only for lightweight runtime checks. Set SCILAB_GUI_BIN and
SCILAB_CLI_BIN when the executables are not on PATH.
Related MCP server: SimuBridge
Install and run
uv sync
uv run xcos-mcpThe default transport is stdio. For streamable HTTP:
XCOS_SERVER_MODE=http XCOS_SERVER_PORT=8000 uv run xcos-mcpExample MCP client configuration:
{
"command": "/absolute/path/to/xcos-mcp/.venv/bin/python",
"args": ["-m", "xcos_mcp"],
"env": {
"SCILAB_GUI_BIN": "/absolute/path/to/scilab",
"SCILAB_CLI_BIN": "/absolute/path/to/scilab-cli"
}
}Tools
Tool | Purpose |
| Check MCP responsiveness. |
| Report Scilab paths, version, and headless support. |
| Discover interfaces from the installed block macros. |
| Read an installed block interface definition. |
| Ask Xcos to export a native one-block diagram. |
| Report blocks, links, duration, and |
| Structurally check and atomically save Xcos XML, preserving diagram geometry by default. |
| Reformat simple diagrams into left-to-right signal lanes without changing equations. |
| Import a diagram using real Scilab/Xcos. |
| Simulate a diagram; return named series inline or persist raw recorder data as an artifact. |
| Read selected signals and a bounded time window from a persisted simulation artifact. |
| Exercise the real first-order vertical slice. |
| Calculate standard response and control-effort metrics. |
Numerical extraction currently requires each requested signal to terminate in
a TOWS_c block. Use inspect_xcos_model to find the configured variable
names, then pass those names to simulate_xcos_model.
Generated diagrams should be readable as well as executable. Xcos has native
splitter placement and link-routing behavior that is not faithfully available
through serialized XML alone. Therefore save_xcos_model preserves geometry
by default. layout_xcos_model is available for simple graphs, but deliberately
declines diagrams containing SPLIT_f junctions rather than producing a
misleading layout. Use Xcos's Format -> Auto-Position for selected splitters
and Format -> Link Style -> Optimal for selected links until native layout
automation is exposed safely through the MCP.
simulate_xcos_model defaults to result_mode="inline" for small numerical
jobs. For long, high-rate, or many-signal simulations, set
result_mode="artifact". The server stores raw per-signal CSV files and a
manifest under .xcos-mcp/artifacts/simulations, returns compact metadata, and
lets the client retrieve only the signals and time windows it needs with
read_xcos_simulation_artifact. This prevents raw time series from needlessly
occupying an LLM tool-response context. Artifact reads are capped at 10,000
numeric values in total, with the effective per-signal sample limit reported
in each response.
Spacecraft example
The coupled LEO example builds a native Xcos diagram and then uses this generic MCP server to inspect, validate, and simulate it for 12,000 seconds. It combines a propagated 3D J2 orbit, thin-atmosphere drag, eclipse-gated photon pressure, a solar-wind sensitivity, nonlinear quaternion dynamics, gravity-gradient and centre-of-pressure torques, and three-axis reaction-wheel control. All 24 telemetry channels return to the MCP client as numerical series.
PYTHONPATH=src uv run python examples/space/coupled_leo/run.pyFilesystem policy
Model reads and writes are restricted to the server working directory and the
project root by default. Set XCOS_ALLOWED_MODEL_ROOTS to a platform-separated
list of explicit roots. Generated templates and reference-run artifacts go to
.xcos-mcp/artifacts, or to XCOS_ARTIFACT_DIR when configured.
Development
uv run pytest -q -m "not integration"
SCILAB_GUI_BIN=/path/to/scilab uv run pytest -q -m integration
uv build
uv run python scripts/check_wheel.py dist/xcos_mcp-*.whlSee architecture for component boundaries and limitations for the deliberately deferred engineering work.
Licence and provenance
The current source tree is an independent implementation licensed under GNU GPL version 3 only; see LICENSE. It does not redistribute Scilab macros, block catalogues, icons, or reference diagrams. Installed Scilab files are discovered at runtime.
Available Tools
11 toolsanalyze_step_responseC
Calculate rise, settling, overshoot, error, and optional control-effort metrics.
Inputs: time (required), signal (required), reference (required), control, +1 more. Returns: object
create_xcos_block_templateC
Ask real Xcos to export a one-block diagram and return its XML.
Inputs: name (required), timeout_seconds. Returns: object
get_xcos_block_sourceC
Read an installed block's Scilab interface source for accurate configuration.
Inputs: name (required). Returns: object
get_xcos_runtimeA
Report the discovered Scilab CLI, Xcos-capable GUI, and exact version.
Inputs: no named parameters. Returns: object
inspect_xcos_modelC
Inspect a saved Xcos diagram, including blocks, links, and recorded outputs.
Inputs: model_path (required). Returns: object
list_xcos_blocksC
List block interfaces discovered from the installed Xcos macros.
Inputs: limit, query. Returns: object
pingA
Check that the MCP process is responsive.
Inputs: no named parameters. Returns: object
save_xcos_modelB
Validate basic structure and atomically save Xcos XML inside an allowed root.
Inputs: output_path (required), xml_content (required), overwrite. Returns: object
simulate_first_order_modelC
Build and simulate G(s)=1/(s+1) in real Xcos, returning its numerical response.
Inputs: max_samples, timeout_seconds, duration_seconds. Returns: object
simulate_xcos_modelC
Run a real diagram for any positive duration and return requested TOWS_c series.
Inputs: outputs (required), model_path (required), duration_seconds (required), max_samples, +1 more. Returns: object
validate_xcos_modelC
Perform structural checks and import the diagram with real Scilab/Xcos.
Inputs: model_path (required), timeout_seconds. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have clearly distinct purposes, but validate_xcos_model and save_xcos_model both perform structural validation, and simulate_first_order_model overlaps functionally with the generic simulate_xcos_model. Descriptions help disambiguate, but an agent could hesitate between the specific and general simulation tools.
Names follow a snake_case verb_noun pattern consistently, with domain-specific prefixes (get_xcos_runtime, list_xcos_blocks). Minor deviations: ping lacks a verb_noun structure, and some tools omit the xcos prefix (simulate_first_order_model, analyze_step_response).
11 tools is well within the ideal range and each tool appears to earn its place, covering discovery, block inspection, model handling, simulation, and analysis without excessive redundancy.
The set covers environment discovery, block inspection, model validation, saving, and simulation well, but lacks tools to construct or modify arbitrary models (e.g., add blocks, connect links, set parameters). Only a one-block template can be created, which is a notable gap for building general Xcos diagrams.
Maintenance
Related MCP Connectors
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server manager that acts as a proxy/multiplexer, enabling connections to multiple MCP servers simultaneously and providing JavaScript code execution with access to all connected MCP tools. Supports both stdio and HTTP transports with OAuth authentication, batch tool invocation, and dynamic server management.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to control MATLAB Simulink models through natural language, providing tools for model creation, block management, wiring, simulation, and more via a local MCP backend.4MIT
- FlicenseAqualityCmaintenanceEnables exposing custom tools such as dice rolling and integer addition as MCP servers over stdio and HTTP transports.2-
- FlicenseNot gradedqualityCmaintenanceEnables secure discovery and invocation of sandboxed filesystem, repository inspection, and utility tools through a unified MCP client with schema validation, timeouts, and execution traces.-