fdmnes-mcp

MCP (Model Context Protocol) server that wraps FDMNES — the ab-initio Fortran code for X-ray spectroscopy by Yves Joly at Institut Néel CNRS, Grenoble. Drive FDMNES through Claude Desktop, Claude Code, Codex CLI, Cline, or any other MCP-aware client with natural-language tool calls.

Build and validate input files, launch parallel mpirun fdmnes_mpi jobs asynchronously, poll status, fetch outputs, plot spectra, and look up any of FDMNES's ~350 input keywords from a source-grounded catalog — without ever leaving the chat.

About FDMNES. FDMNES (Finite Difference Method Near Edge Structure) computes XANES, EXAFS (via the FDMX extension), XMCD, RXS/DAFS, RIXS, NRIXS / X-Raman, optic, and emission spectra. Two solver engines: a 3D real-space finite-difference solver (full-potential) and a multiple-scattering Green's function (muffin-tin). Free download at https://fdmnes.neel.cnrs.fr/. This wrapper does NOT redistribute FDMNES itself — you install FDMNES separately.

Install

1. Install FDMNES

If you haven't already, grab FDMNES from https://fdmnes.neel.cnrs.fr/download/. You want either:

• the parallel Linux executable (parallel_fdmnes zip — recommended), or
• the Fortran source + the MUMPS / ScaLAPACK / OpenMPI toolchain (build it yourself).

Make sure your FDMNES binary is executable (chmod +x <binary>) and ideally on $PATH. The MCP server autodetects it from $PATH, then from common install directories (~/fdmnes, ~/FDMNES, /opt/fdmnes, /usr/local/fdmnes); override with the FDMNES_BIN env var if needed.

2. Install fdmnes-mcp

From PyPI (recommended once a release is published):

pip install fdmnes-mcp

From GitHub main (bleeding edge):

pip install git+https://github.com/Joint-Photon-Sciences-Institute/fdmnes-mcp.git

From a local checkout (for development):

git clone https://github.com/Joint-Photon-Sciences-Institute/fdmnes-mcp.git
cd fdmnes-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

After install, the fdmnes-mcp console script is on your $PATH and equivalent to python -m fdmnes_mcp.

3. Verify the wiring

fdmnes-mcp --info     # or: python -m fdmnes_mcp --info

Prints the resolved paths and flags anything missing. Example output:

fdmnes-mcp configuration
========================

  FDMNES binary       : /usr/local/bin/fdmnes_mpi
      exists / x-bit  : True / True
  Bundle directory    : /opt/fdmnes/linux_bundle/fdmnes_Linux
      exists          : True
  Examples directory  : /opt/fdmnes/linux_bundle/fdmnes_Linux/Sim/Test_stand/in
      exists          : True
  Docs directory      : /.../site-packages/fdmnes_mcp/data/docs  (packaged)
      exists          : True
  Work directory      : /home/you/fdmnes-jobs
  mpirun default -np  : 4

All paths resolved.

Register with your MCP client

Claude Code

claude mcp add fdmnes -- fdmnes-mcp

(If fdmnes-mcp isn't on your $PATH, use the absolute path returned by which fdmnes-mcp.)

Claude Desktop

Edit claude_desktop_config.json (location varies by OS: ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows, ~/.config/Claude/ on Linux):

{
  "mcpServers": {
    "fdmnes": {
      "command": "fdmnes-mcp"
    }
  }
}

To override defaults via environment variables:

{
  "mcpServers": {
    "fdmnes": {
      "command": "fdmnes-mcp",
      "env": {
        "FDMNES_BIN": "/opt/fdmnes/fdmnes_mpi",
        "FDMNES_MPI_DEFAULT_NP": "8"
      }
    }
  }
}

Codex CLI

In your ~/.codex/config.toml:

[mcp_servers.fdmnes]
command = "fdmnes-mcp"

Cline (VS Code)

Edit cline_mcp_settings.json (Cline → MCP Servers → Configure):

{
  "mcpServers": {
    "fdmnes": {
      "command": "fdmnes-mcp",
      "transport": "stdio"
    }
  }
}

Any generic MCP client

Run the binary as a stdio server:

fdmnes-mcp

Quick start (Claude)

After registering, try:

List the bundled FDMNES examples, then run the Cu K-edge one on 4 ranks and plot the convolved spectrum when it finishes.

Claude will call (roughly):

1. fdmnes_list_examples → see Cu
2. fdmnes_run_example(example_name="Cu", np=4) → get a job_id
3. fdmnes_status(job_id) until status == "completed"
4. fdmnes_fetch_result(job_id) → returns output paths
5. fdmnes_plot_spectrum(path=".../Cu_conv.txt") → renders the spectrum

Or for a new material:

Scaffold an SCF XANES job for Fe₂O₃ at the Fe K-edge with Hubbard U = 5 eV under ~/jobs/fe2o3/, then run it on 8 ranks.

Configuration

All paths are auto-detected with sensible fallbacks. Override any of them via environment variables:

Call fdmnes_get_config inside a Claude session at any time to see what's currently active.

Tool reference

27 tools across 6 categories (+ 8 resources). See src/fdmnes_mcp/tools/ for implementations.

I/O & inspection

Authoring

Execution (async)

Plotting

Workflow templates

Escape hatch

Resources

Read-only docs available at:

Architecture

src/fdmnes_mcp/
├── __main__.py                # entry point with --info / --help / --version
├── server.py                  # FastMCP setup + tool/resource registration
├── config.py                  # autodetection + env-var-driven paths
├── session.py                 # JobManager (asyncio subprocess registry)
├── parsers/
│   ├── input_parser.py        # _inp.txt → structured blocks
│   ├── spectrum_parser.py     # X.txt / X_conv.txt → numpy arrays
│   ├── bav_parser.py          # _bav.txt → highlights
│   └── keyword_db.py          # ~770-entry keyword DB (mined from packaged docs)
├── tools/
│   ├── io_tools.py
│   ├── authoring_tools.py
│   ├── execution_tools.py     # async run / status / fetch
│   ├── plot_tools.py
│   ├── template_tools.py      # workflow one-shots
│   └── shell_tools.py
├── resources/docs.py          # fdmnes:// resource URIs
└── data/docs/                 # packaged reference docs (markdown)

The keyword DB is mined from the shipped data/docs/keyword-reference.md at server startup. Override with FDMNES_DOCS_DIR to point at a different docs tree (e.g. a forked / extended catalog).

Citing FDMNES

If you publish results obtained with FDMNES (with or without this wrapper), the FDMNES author asks that you cite the following, as listed in the FDMNES User's Guide:

• Main FDMNES paper: O. Bunau and Y. Joly, J. Phys.: Condens. Matter 21, 345501 (2009).
• MUMPS-accelerated FDM: S. A. Guda et al., J. Chem. Theory Comput. 11, 4512-4521 (2015).
• FDMX EXAFS extension: J. D. Bourke, C. T. Chantler, Y. Joly, J. Synchrotron Rad. 23, 551-559 (2016).
• Surface RXD: Y. Joly et al., J. Chem. Theory Comput. 14, 973-980 (2018).
• X-Raman / NRIXS: Y. Joly, C. Cavallari, S. A. Guda, C. J. Sahle, J. Chem. Theory Comput. 13, 2172-2177 (2017).
• International Tables for Crystallography, Volume I (2021, 2022).

This wrapper does not need a separate citation, but a link or acknowledgement is appreciated:

FDMNES jobs were driven through the fdmnes-mcp wrapper (Joint Photon Sciences Institute, https://github.com/Joint-Photon-Sciences-Institute/fdmnes-mcp).

Contributing & releases

Issues and pull requests welcome at https://github.com/Joint-Photon-Sciences-Institute/fdmnes-mcp.

Release process (for maintainers):

1. Bump version in pyproject.toml.
2. Commit, tag (git tag v0.x.y), push the tag (git push --tags).
3. The Publish to PyPI GitHub Actions workflow builds and publishes via PyPI Trusted Publishing. No API tokens needed in the repo — the project's PyPI page must be configured to trust this repo + workflow on first release (one-time setup).

License

This wrapper is released under the BSD 3-Clause License. FDMNES itself is independent software with its own distribution terms; see https://fdmnes.neel.cnrs.fr/ for FDMNES licensing questions.

Acknowledgements

Built in the style of xraylarch-mcp. Thanks to Yves Joly and the FDMNES developers for making the code freely available, and to the MCP / FastMCP authors for the protocol that makes wrappers like this trivial.