flux-mcp
🌀 Agentic MCP tools for Flux Framework
Related Projects
- 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)
flux-mcp-stdio runs the stdio server for agents (Claude Code, Codex, Google ADK, AWS Strands, and others) 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:
~/.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: HOME, USER, LOGNAME and SHELL from the password database, and the login PATH (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 (starts the HTTP server inside a test instance):
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?)
- flux-sched
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.22
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| flux_mcp-0.0.22.tar.gz | 79.1 kB | Without provenance | Details for flux_mcp-0.0.22.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| flux_mcp-0.0.22-py3-none-any.whl | Python 3 | none | any | Details for flux_mcp-0.0.22-py3-none-any.whl |
Total release size: 160.2 kB
Release files / flux_mcp-0.0.22.tar.gz
| Download URL | flux_mcp-0.0.22.tar.gz |
|---|---|
| Size | 79.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
56f4f3ace10e922626b7badbe18d25b12e0e3eea055615f7d475e2b2ef7c45c7
|
|
BLAKE2b-256 checksum How to use checksums |
8879119e9e5b5f3c1a7ed08d7ca725792dc9f491485969c5c10dd4b85327879b
|
| 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.22-py3-none-any.whl
| Download URL | flux_mcp-0.0.22-py3-none-any.whl |
|---|---|
| Size | 81.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2ec4299ad11e9cb859c113385a5566dfe02547276abfdace4527b637e0e5331f
|
|
BLAKE2b-256 checksum How to use checksums |
a4e4bbed7e525b09d5232387810f3401b703c40e7341c94136b96cc769604140
|
| 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.22
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.