Skip to main content
Glama

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 data

The 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-run on 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-mcp

The default transport is stdio. For streamable HTTP:

XCOS_SERVER_MODE=http XCOS_SERVER_PORT=8000 uv run xcos-mcp

Example 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

ping

Check MCP responsiveness.

get_xcos_runtime

Report Scilab paths, version, and headless support.

list_xcos_blocks

Discover interfaces from the installed block macros.

get_xcos_block_source

Read an installed block interface definition.

create_xcos_block_template

Ask Xcos to export a native one-block diagram.

inspect_xcos_model

Report blocks, links, duration, and TOWS_c outputs.

save_xcos_model

Structurally check and atomically save Xcos XML, preserving diagram geometry by default.

layout_xcos_model

Reformat simple diagrams into left-to-right signal lanes without changing equations.

validate_xcos_model

Import a diagram using real Scilab/Xcos.

simulate_xcos_model

Simulate a diagram; return named series inline or persist raw recorder data as an artifact.

read_xcos_simulation_artifact

Read selected signals and a bounded time window from a persisted simulation artifact.

simulate_first_order_model

Exercise the real first-order vertical slice.

analyze_step_response

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.py

Filesystem 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-*.whl

See 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 tools
analyze_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

    B3/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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).

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      4
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      Enables exposing custom tools such as dice rolling and integer addition as MCP servers over stdio and HTTP transports.
      2
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables secure discovery and invocation of sandboxed filesystem, repository inspection, and utility tools through a unified MCP client with schema validation, timeouts, and execution traces.
      -