Skip to main content

flux-mcp

🌀 Agentic MCP tools for Flux Framework

PyPI version DOI

https://github.com/converged-computing/flux-mcp/raw/main/img/flux-mcp-small.png

  • fractale-mcp: (fractale) MCP orchestration (agents, databases, ui interfaces).
  • hpc-mcp: HPC tools for a larger set of HPC and converged computing use cases.

Usage

These Flux MCP tools can be used via a standalone server, or combined with other tools. Note that along with flux-python (comes packaged with Flux, or pip install flux-python==<version> you can optionally install flux-sched-py for flux-sched functionality.

Server

We provide examples for fastmcp and a vanilla mcp (stdio) setup. Neither requirements are added to the install directly, so it's up to the user (you) to install. Tests are performed with fastmcp.

fastmcp

You will need fastapi and fastmcp installed.

# fastmcp
pip install fastmcp fastapi
# in the devcontainer
pip install fastmcp fastapi --break-system-packages

To start the demo server:

# Vanilla MCP (with cli)
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}' | python3 -m flux_mcp.server | jq

# Initialize and list tools
(echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "manual-test", "version": "1.0"}}}';
 echo '{"jsonrpc": "2.0", "method": "notifications/initialized"}';
 echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}') | python3 -m flux_mcp.server | jq

# FastMCP
python3 -m flux_mcp.server.fastmcp

Agents (stdio)

See agents for Claude Code, Codex, Google ADK and AWS Strands, with tests for each and a devcontainer that has Flux and flux-mcp.

flux-mcp-stdio runs the stdio server for agents such as Claude Code, Codex, Google ADK and AWS Strands that you start inside a Flux instance you own.

flux python -m venv ~/.flux-mcp/venv
~/.flux-mcp/venv/bin/pip install flux-mcp
# then point your agent at this command
~/.flux-mcp/venv/bin/flux-mcp-stdio

It exits with an error if FLUX_URI is unset (rather than falling back to the system instance). If the Flux Python bindings are not importable, it re-runs itself under flux env.

Jobs never receive the server environment. A job gets exactly the environment the agent passes, or else a minimal user environment. That has HOME, USER, LOGNAME and SHELL from the password database, and the login PATH from ENV_PATH in /etc/login.defs plus the directory containing flux. Commands run with flux exec get the same minimal environment.

Docker

We have a provided Dockerfile that builds and includes mcp-server to provide the basic set of Flux endpoints (submit, info, cancel, etc) via the configuration file flux-mcp.yaml. You can tweak that file and build, or just use from our GitHub packages registry.

docker build -t ghcr.io/converged-computing/flux-mcp:latest .
docker run -it -p 8089:8089 ghcr.io/converged-computing/flux-mcp:latest

Testing

You need pytest

pip install pytest --break-system-packages

I will add tools to git as I write tests for them. To test, start the fastmcp server in one terminal:

python3 -m flux_mcp.server.fastmcp

To test flux-sched, ensure libreapi_cli.so is on the LD_LIBRARY_PATH of the server:

export LD_LIBRARY_PATH=/usr/lib/flux/
python3 -m flux_mcp.server.fastmcp

In another terminal, run the test. You'll need to pip install pytest pytest-asyncio

pytest -xs tests/test_flux_validate.py
pytest -xs tests/test_flux_counts.py
pytest -xs tests/test_flux_job_delegation.py
pytest -xs tests/test_flux_job_core.py
pytest -xs tests/test_transformers.py
pytest -xs tests/test_flux_resource.py

# Requires libreapi_cli.so
pytest -xs tests/test_flux_sched.py

# or
pytest -xs tests/test_*.py

To run the whole suite the way CI does, with the HTTP server inside a test instance, run this.

flux start --test-size=2 tests/run-in-flux.sh -v --ignore=tests/test_flux_sched.py tests

Tools

Tools to add:

  • flux
    • flux-sched
      • grow
      • shrink
      • create resource graph
      • match allocate
      • cancel
      • partial-cancel
      • satisfy
    • flux-core
      • submit jobs
      • job info
      • cancel job
      • validator
        • counter
        • batch jobs
        • canonical jobspec
        • json jobspec
    • topology?
    • delegation
    • local flux URI
    • translation (the transformers?)

License

HPCIC DevTools is distributed under the terms of the MIT license. All new contributions must be made under this license.

See LICENSE, COPYRIGHT, and NOTICE for details.

SPDX-License-Identifier: (MIT)

LLNL-CODE- 842614

Metadata

Release files for flux-mcp 0.0.23

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flux-mcp 0.0.23
File Size Uploaded Provenance Actions
flux_mcp-0.0.23.tar.gz 79.2 kB Without provenance Details for flux_mcp-0.0.23.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flux-mcp 0.0.23
File Interpreter ABI Platform Actions
flux_mcp-0.0.23-py3-none-any.whl Python 3 none any Details for flux_mcp-0.0.23-py3-none-any.whl

Total release size: 160.4 kB

Release files / flux_mcp-0.0.23.tar.gz

Download URL flux_mcp-0.0.23.tar.gz
Size 79.2 kB
Tags Source
SHA-256 checksum
How to use checksums
74fb3ba3418d9c06a0e61e6ffad1f263bb20edfd25df9f8ed43581d26cb39be7
BLAKE2b-256 checksum
How to use checksums
d390461511fd484668c415ad1f83a6b8627b41040589fd9b514fc64754d63bef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.2

Release files / flux_mcp-0.0.23-py3-none-any.whl

Download URL flux_mcp-0.0.23-py3-none-any.whl
Size 81.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1f8e847a10fe52fe7912ac4d5b802e1c4a968261d31cdc143a1d9789913727ed
BLAKE2b-256 checksum
How to use checksums
8d42bed10f179afc761cc93137ff3781ecefbf91139a2023e38c8aa416f28648
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.2

Security for flux-mcp 0.0.23

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page