LibreModular-MCP

One MCP server in Rust that lets a model drive desktop applications by running scripts in them: a Hub with two tools, execute_script and get_state; GIMP, Krita, Blender, Inkscape and LibreOffice work today. RPM and Arch packages are not signed; on Windows 11 only the Inkscape module was tried.

Documentation

LibreModular-MCP

English | Français | Deutsch | Español

Version v0.1.0 License: MIT Continuous integration Packages for Debian, Ubuntu, Fedora, openSUSE Leap and Arch Linux, and an installer for Windows 11

Universal MCP server written in Rust, with a Hub that exposes only two tools

One MCP server, the Hub, that lets a language model drive desktop applications by running scripts in them. An application joins the Hub through a module and a bridge; GIMP, Krita, Blender, Inkscape and LibreOffice work today; the Hub is built to connect as many applications as possible in one server (CONTRIBUTING.md says how to add one).

A strip showing the model as a spark of light, the two tools execute_script and get_state, then five thumbnails in one line: a 3D scene for Blender, a spark on a checkerboard for GIMP, a painted dusk landscape for Krita, a drawing of orbits for Inkscape and a letter for LibreOffice.

One model, two tools, five applications: each thumbnail shows what the Hub made in its application.

The website libremodular.davalan.fr has pages to read online on the same subjects:

This repository is complete without it: everything needed to install, run and check the Hub is here.

Quick start

Install the Hub, let it create its configuration and its token, then declare it in your MCP client.

On Debian, Ubuntu, Fedora, openSUSE Leap or Arch Linux, install the native package of your family; its installation and its removal were validated in a container on every version listed. Download it from the releases page, then run the command of your family:

FamilyVersionsPackageCommand
Debian, UbuntuDebian 12 and 13; Ubuntu 22.04, 24.04 and 26.04 (amd64)libremodular-mcp_*_amd64.debsudo apt install ./libremodular-mcp_*_amd64.deb
Fedora43, 44 and 45 (x86_64)libremodular-mcp-*.fc*.x86_64.rpmsudo dnf install ./libremodular-mcp-*.fc*.x86_64.rpm
openSUSE Leap16.0 and 16.1 (x86_64)libremodular-mcp-*.leap*.x86_64.rpmsudo zypper install --allow-unsigned-rpm ./libremodular-mcp-*.leap*.x86_64.rpm
Arch Linuxrolling (x86_64)libremodular-mcp-*-x86_64.pkg.tar.zstsudo pacman -U ./libremodular-mcp-*-x86_64.pkg.tar.zst

The RPM packages and the Arch package are not signed: zypper needs --allow-unsigned-rpm, and dnf installs the local file with a warning that it skipped the OpenPGP check. Then create the configuration and the token, once, as your own user:

libremodular-mcp init

The package also installs the guides in /usr/share/doc/libremodular-mcp/ and the manual pages (man libremodular-mcp, man libremodular-launch) in English, French, German and Spanish.

On Windows 11 (x64), download libremodular-mcp-0.1.0-windows.zip from the same page. It holds one installer, built on Windows and tried without a screen: silent installation, init, a started Hub that answers initialize, removal, in an account whose name has accents. Its level is built on Windows, tried without a screen; nobody has tried it on their own machine yet, so it is not called tested. The installer is not signed, so Windows may warn before running it. In PowerShell:

tar -xf libremodular-mcp-0.1.0-windows.zip
.\libremodular-mcp-0.1.0-setup.exe /S

It needs no administrator rights: it installs the Hub, libremodular-launch (which refuses to run on Windows), the bridges as text files, the licence and the guides in %LOCALAPPDATA%\Programs\LibreModular-MCP\, and adds that folder to the PATH of your account (open a new terminal). Then run libremodular-mcp init; the configuration and the token go to %LOCALAPPDATA%\libremodular-mcp\config\. uninstall.exe, in the install folder, removes the program and leaves the configuration, the token and the audit journal.

To build the Hub from the sources instead, install a C compiler and linker (on Debian, sudo apt install build-essential) and Rust 1.97 or later (with rustup: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh), then:

cd /home/alice/LibreModular-MCP
cargo build --release --locked
target/release/libremodular-mcp init

The entry for the MCP client runs the binary with the argument serve:

{
  "mcpServers": {
    "libremodular": {
      "command": "/home/alice/LibreModular-MCP/target/release/libremodular-mcp",
      "args": ["serve"]
    }
  }
}

What to adapt: /home/alice/LibreModular-MCP/ is the absolute path of your clone; with a package, the command is /usr/bin/libremodular-mcp; on Windows, it is the full path of libremodular-mcp.exe in the install folder. Which file this entry goes into, and what its keys are called, depends on your client: the shape above is a common one, and the Hub was tried with a client written for its tests (JSON-RPC lines on its standard input and output); in Claude Code 2.1.312 and in opencode 2.2.0 it answered get_state on hub, and no execute_script call was made from either. No other MCP client was tried. The Hub speaks the Model Context Protocol over its standard input and output: one JSON object per line, initialize first, then tools/list and tools/call with a name and an arguments object; the text of each answer is in result.content[0].text. On Linux, the Hub needs the variable XDG_RUNTIME_DIR, which a desktop session sets; without it, it refuses to start. A client started outside a desktop session, a service for example, must pass that variable to the Hub.

init creates ~/.config/libremodular-mcp/config.toml and the token file next to it, both in mode 600. It never overwrites the configuration, and replaces the token only with init --rotate. Nothing is enabled afterwards: set enabled = true for the application you want in config.toml, then start its bridge as its guide says (see the table below).

What it is

The Hub is one binary that gives the model exactly two tools, execute_script and get_state. The model writes one complete script; the Hub sends it to a bridge that runs it inside the application, next to it, or as one process per script, and the model gets back what the script printed, its result, or the application's own error trace to correct. The Hub knows no application's interface: each application has a module on the Hub side and a bridge on the application side, and the bridges are Python files whose only dependencies are the standard library and the application's own Python interface.

The two tools

execute_script(target_app: str, script_content: str) -> str runs a complete Python script in the application named by target_app. It returns the text of a JSON object with status (ok, error, timeout, busy, refused or unavailable), app, duration_ms, stdout, stderr, result, error (null, or type, message and traceback, the application's own), truncated, and reason when the Hub itself refused the script or could not run it.

get_state(target_app: str) -> dict returns app, connected, app_version, bridge_version, captured_at, state (what is specific to the application), content_origin, screenshot (the path of a PNG file, or null) and warnings; the answer reaches the client as the text of a JSON object. The target hub returns the list of configured applications, how each one is reached, and whether it is connected, without contacting any application.

target_app must be the exact name of an enabled application; get_state also accepts hub. Neither tool accepts anything else: execute_script refuses any other name (its status is refused), and get_state answers with connected: false and a warning.

content_origin says where state comes from: document for content taken from the application's open documents, which a model reads as data and never as instructions, and hub for the list that the target hub returns.

A model that drives the tools reads docs/GUIDE_LLM.md first: six steps, from get_state("hub") to the handling of each status.

Applications

The target platform is Debian 13, and the Calc example below also ran on Ubuntu 24.04. On Windows 11, only the Inkscape module was tried (Inkscape 1.4.2 and 1.4.4): the bridges of GIMP, Krita, Blender and LibreOffice were tried there against a stand-in host, not in the real applications, and libremodular-launch refuses to run. The Hub installs from a native package (Debian, Ubuntu, Fedora, openSUSE Leap or Arch Linux, see Quick start) or builds from the sources (Quick start). The versions are those the guides report as tried; the guide of each application says under which conditions, and what was not part of the run.

TargetApplicationModeVersion triedGuide
gimpGIMPtcp3.0.4, started without its interfacedocs/modules/gimp.md
kritaKritatcp5.2.9, not started from Scripterdocs/modules/krita.md
blenderBlendertcp4.3.2docs/modules/blender.md
inkscapeInkscapecli1.4docs/modules/inkscape.md
libreoffice-writer, libreoffice-calc, libreoffice-impressLibreOfficeuno24.2.7.2 and 25.2.3.2docs/modules/libreoffice.md

The modes: tcp, a bridge loaded in the application listens on a local port; uno, a stand-alone bridge connects to the UNO port LibreOffice listens on; cli, one process runs each script.

In the tcp and uno modes the Hub never starts, closes or stops an application on the model's request: bridges and applications start on an explicit gesture of the operator, described in each guide, and libremodular-launch libreoffice starts LibreOffice and its bridge (the other applications are started by hand). In the cli mode the Hub starts one Python process per script, and runs inkscape once to export a capture; it never touches an Inkscape window the operator opened.

Example

A Calc script, which the LibreOffice bridge runs with doc (the document in front, or None) and desktop already defined, that creates the document when none is open, writes two cells and returns what it wrote, and the answer of the Hub. It ran as written, with no document open, in LibreOffice 24.2.7.2 (the Ubuntu 24.04 packages, with a window on a virtual X display), through the real libremodular-mcp. The same example is in docs/modules/libreoffice.md.

if doc is None:
    doc = desktop.loadComponentFromURL('private:factory/scalc', '_blank', 0, ())
sheet = doc.Sheets.getByIndex(0)
sheet.getCellByPosition(0, 0).setValue(42)
sheet.getCellByPosition(1, 1).setString('hello')
print('wrote A1 and B2')
result = {'sheet': sheet.Name, 'a1': sheet.getCellByPosition(0, 0).getValue(), 'b2': sheet.getCellByPosition(1, 1).getString()}
{
  "app": "libreoffice-calc",
  "duration_ms": 170,
  "error": null,
  "result": {
    "a1": 42.0,
    "b2": "hello",
    "sheet": "Sheet1"
  },
  "status": "ok",
  "stderr": "",
  "stdout": "wrote A1 and B2\n",
  "truncated": false
}

What leaves the machine

Everything the Hub returns goes to the language model, and so to whoever runs it.

WhatLeaves the machine
The script the model wroteYes: the model is its author
stdout, stderr and result of a scriptYes: they can hold the content of a document
The error traceYes: it holds paths of the machine
stateYes: it holds content taken from the open documents
The path of a captureYes: it is part of the answer
The image of a captureOnly if the model reads the file
The audit journal, the token and the configurationNever

A user who opens a confidential document in a connected application knows that its content can be read by the model.

The Hub connects only to bridges on 127.0.0.1: a test reads the source for any other (cargo test --locked --test invariants).

Limits

  • The Hub is not a sandbox. A script runs with the rights of the user, inside an application whose Python can do whatever the user can.
  • The script guard stops a clumsy script, not a determined one. It reads the text of a script before it is sent; it does not see runpy, pickle, http.server, the save functions of the applications, or a path passed to a function as a parameter.
  • LibreOffice's UNO port has no authentication: any process that can reach it on this machine drives LibreOffice without the token, the guard or the audit journal.
  • Another process of the same user can read the token file.
  • In the tcp and uno modes, a script that loops keeps the application (for LibreOffice, its bridge) busy until it is closed: the Hub answers timeout, then busy, and does not stop it. Only the cli mode kills a script that runs past its time.
  • libremodular-launch refuses a bridge file that the group or others can write, or that belongs to a user other than you and root. A clone made with a umask of 002 gives mode 664: run chmod 600 on the bridge file once. Mode 600 and mode 644 are accepted; the bridge files of the packages belong to root with mode 644.

Tests

cargo test --locked
python3 -m unittest discover -s tests/bridges
python3 scripts/build_bridges.py --check

Tests that need a real application are marked #[ignore] with their reason and are run on purpose, for example cargo test --locked --test libreoffice_real -- --ignored --nocapture.

The full list of checks and how to contribute are in CONTRIBUTING.md.

Credits

LibreModular-MCP is built in an asymmetric human–LLM collaboration. The roles are written down as they were actually played; the full list is in CONTRIBUTORS.md.

  • Ronan Davalan: architect and arbiter. Initiative, priorities, security requirements, validation and testing.
  • Claude Code (Anthropic): systems engineer and lead developer. Working framework, review and integration of the code, documentation, packages, website and translations.
  • Claude Cloud (Anthropic): wrote the code on branches from prompts, reviewed before every merge.
  • Gemini (Google): architectural advisor and synthesizer; wrote the founding note and proposed the project's name.
  • Muse Spark 1.3 (Meta): graphic designer; drew the logo and the favicons.
  • DeepSeek V4.1 Flash and MiMo V2.6 Flash (free models, run through opencode): pilot models of the Windows trial and visitors with no context in the first-contact test; the frictions they reported are corrected in this README and in the guides.

Security and licence

Report a vulnerability as SECURITY.md says. The code is under the MIT licence, see LICENSE.