Frama-C MCP server
Commit Nov 11, 2026Enables AI agents to perform abstract interpretation, deductive proof, and ACSL annotation injection using the Frama-C formal verification framework.
Also known as sysprog21/frama-c-mcp
- Stars
- 36
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- MIT
What is Frama-C MCP?
Frama-C enables AI agents to perform abstract interpretation, deductive proof, and ACSL annotation injection using the Frama-C formal verification framework.
Summary generated from the project's README
About Frama-C MCP server
Formal verification of C code through an iterative AI-driven loop is what this server enables. It allows AI agents to perform abstract interpretation using EVA, execute deductive proofs via WP, and inject ACSL annotations into source files. Designed specifically for agentic workflows rather than manual human input, the server operates over stdio and maintains a persistent session state where a single project remains loaded across multiple calls.
Developers connect this server to clients like Claude Desktop or Claude Code to automate the process of proposing, proving, and revising code annotations. The architecture utilizes a Rust-based MCP server and a custom ast-utils Frama-C plugin to manage complex tasks. It features a sandboxing mechanism that creates isolated Frama-C processes for specific functions, allowing an agent to experiment with new annotations without mutating the main project. Users must ensure Frama-C and the plugin are installed in the same opam switch to function correctly.
What you can do with it
- 1Iterative annotation refinementAn agent can propose an ACSL annotation, attempt to prove it, and then use the failure reason to revise the code.
- 2Isolated experimentation with sandboxesA developer can task an agent with testing new annotations on a specific function without affecting the primary codebase.
- 3Automated runtime error checkingYou can ask an agent to check a specific C file for runtime errors and verify its contracts using specific build flags.
- 4Deep investigation of proof failuresAn agent can retrieve detailed information about why a specific goal was not proved, including the hypotheses used by the prover.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesysprog21/frama-c-mcp is public and reachablegithub.com/sysprog21/frama-c-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/sysprog21/frama-c-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubframa-c-mcp
An MCP server that gives an AI agent Frama-C: EVA abstract interpretation, WP deductive proof, ACSL annotation injection, and isolated sandboxes for trying annotations out.
The server is designed to be driven by an agent rather than by a person. An MCP client spawns it and speaks to it over stdio, so there is no command for a human to type. It is built around an iterative loop: propose an annotation, prove it, read why the goal did not close, then revise. The session state follows from that loop rather than from shell use, since one project stays loaded across calls, sandboxes are addressed by name, and proof receipts compare only within a run.
Wire it into Claude Code, Claude Desktop, or any MCP client, then prompt in
English. See Connect an agent and
Prompt patterns. A check subcommand exists for CI and is
the only part intended to be run by hand.
Architecture
┌──────────┐ MCP over stdio ┌────────────────┐ Unix socket ┌─────────────────┐
│ AI agent │◄─────────────────►│ frama-c-mcp │◄─────────────►│ Frama-C main │
└──────────┘ │ Rust server │ │ + ast-utils │
└───────┬────────┘ └─────────────────┘
│ Unix socket per sandbox
▼
┌──────────────────┐
│ Frama-C sandbox │
│ + ast-utils │
│ per experiment │
└──────────────────┘
The server has two required components:
- Rust MCP server: exposes the tools over MCP stdio, translates requests into Frama-C's server protocol, and lazily starts the main Frama-C process on the first project operation.
ast-utilsFrama-C plugin: provides the custom requests for AST access, dependency extraction, ACSL injection, sandboxing, and WP configuration. Build and install it in the same opam switch as Frama-C.
create_sandbox extracts a function together with its type, callee, and global
dependencies into a temporary C file, then starts a separate Frama-C process.
An agent can iterate on annotations there without mutating the main project;
verified sandbox annotations are merged back explicitly.
Session model
The server holds one project: reload_project or the first check loads it,
and later calls operate on that AST. Sandboxes are separate processes,
addressed as experiment_id:function.
The preprocessor surface is nostdinc, include_paths, isystem_paths,
defines, force_includes, and machdep, applied in that order. Each value is
written without its compiler flag. nostdinc drops the preprocessor's default
system directories and isystem_paths are searched after include_paths; pair
them to put a modeled libc where the real system headers would otherwise be
found. Both are part of the load identity a proof receipt is hashed over,
because they decide which declarations a file is compiled against.
Quick start
Build the Frama-C plugin, build and install the server, then point an MCP client at it. The plugin and Frama-C must be installed in the same opam switch.
Prerequisites
- Frama-C 32.1 or newer (CI exercises 33.0)
- OCaml 4.14.2, opam, and dune >= 3.0
- Rust 2021 toolchain
- WP provers: Alt-Ergo, with Z3 and CVC5 optional
Build
# Name the switch that holds Frama-C. A bare `opam env` picks up whichever
# switch happens to be active, which is the failure described below.
eval $(opam env --switch=frama-c-33 --set-switch)
cd ast-utils
dune build && dune install
cd ..
cargo build --release
dune resolves Frama-C through the opam switch, not through PATH. Setting
only PATH builds the plugin against whichever switch is active and fails with
unbound modules in files you did not touch.
After changing the plugin, run dune clean && dune build && dune install.
Incremental builds may not relink the installed .cmxs.
Prebuilt binaries
Every push to main that passes the full test lane replaces a rolling
latest release, so the download link never moves:
# Linux x86_64
curl -sSfL -o frama-c-mcp.tar.gz \
https://github.com/sysprog21/frama-c-mcp/releases/download/latest/frama-c-mcp-x86_64-unknown-linux-gnu.tar.gz
# macOS arm64
curl -sSfL -o frama-c-mcp.tar.gz \
https://github.com/sysprog21/frama-c-mcp/releases/download/latest/frama-c-mcp-aarch64-apple-darwin.tar.gz
tar xzf frama-c-mcp.tar.gz
mkdir -p ~/.local/bin
install -m 755 frama-c-mcp ~/.local/bin/
There is no Windows build: the transport speaks Unix sockets and Frama-C does not target Windows either.
The tarball holds the Rust MCP server and nothing else. It is half the product:
most tools return invalid without the ast-utils plugin, and that plugin
still has to be built from source in the opam switch holding your Frama-C,
because a .cmxs is tied to the exact OCaml and Frama-C that compiled it. So a
download is dune build && dune install under Build plus this binary
in place of cargo build --release, not a way to skip the switch.
Install
make install # to ~/.local/bin
make install BINDIR=/usr/local/bin
make install builds and installs both the Rust binary and the ast-utils
plugin. It runs dune through opam exec, so the plugin lands in the active
switch; select the switch holding Frama-C before running it. The install fails
if the resulting plugin is not loadable by that switch's frama-c. BINDIR
must be writable without sudo, which would discard the opam environment.
It finishes by pointing whichever agents are installed at the binary it just
placed: Claude Code through claude mcp add, and codex by adding an
[mcp_servers.frama-c] section to ~/.codex/config.toml when that file exists
and has no such section. An agent that is not installed is skipped rather than
failing the install, and an existing codex section is left alone rather than
rewritten. Run make register on its own to redo just that step.
Use it instead of copying over an existing binary. On macOS, replacing an
executed binary in place can leave a stale code-signature blob and cause every
subsequent execution to fail with SIGKILL (Code Signature Invalid). The
install goes through a temporary file, ad-hoc signs it, runs it once, and then
renames it into place.
The other targets: make builds the release binary, make indent runs shfmt
over the shell scripts and commentflow over the sources that carry comments,
and make clean removes target/ and the plugin's _build/.
Connect an agent
Declare the server in .mcp.json for a project, or in
claude_desktop_config.json for Claude Desktop:
{
"mcpServers": {
"frama-c": {
"command": "/path/to/frama-c-mcp",
"args": ["--frama-c", "/path/to/frama-c"]
}
}
}
The client spawns that command and speaks MCP over its stdin and stdout, so
there is nothing to start beforehand; run the binary from a terminal and it
simply waits on stdin. Frama-C itself is spawned lazily, on the agent's first
project operation, which is why a misconfigured --frama-c surfaces on the
first check rather than at startup.
The arguments the client passes:
| Flag | Default | Description |
|---|---|---|
--frama-c |
frama-c |
Path to the Frama-C binary |
--max-sandboxes |
32 |
Maximum concurrent sandbox Frama-C processes |
--socket |
none | Deprecated; ignored when set because sockets are generated per process |
Once connected, drive it in English rather than by naming tools; the agent picks the calls. Prompt patterns is the table of what to say.
Pair it with agent skills
The server supplies evidence and says nothing about how to write ACSL or when a proof counts as done. An agent skill carries that half.
skills/frama-c-proofreader ships in this repository, in the Agent Skills
layout (SKILL.md, references/, an agents/openai.yaml for Codex). It tells
an agent to prefer these tools, to dry-run an injection before applying it, to
run a smoke test before calling a function verified, and to report environment
failures, static proof gaps, runtime violations and proofs under assumptions as
four separate outcomes. Its scripts/verify.sh runs WP over the bundled
abs-int pair, expecting the overflow gap in one and a full proof of the
other, and E-ACSL over the buggy half where E-ACSL is installed. Copy the
directory into the agent's skills location:
cp -r skills/frama-c-proofreader ~/.claude/skills/ # Claude Code
cp -r skills/frama-c-proofreader ~/.agents/skills/ # Codex
CLI escape hatch for CI
The check subcommand runs the same code path as the check tool and prints
its JSON payload, so a pipeline can use the server without an agent and without
speaking MCP. It is the one entry point meant to be typed:
./target/release/frama-c-mcp check src/foo.c --function foo \
-I include -D NDEBUG --force-include builtins.h --require-complete
--require-complete exits non-zero when incomplete[] is non-empty, which is
the difference between "nothing was reported" and "everything was checked".
The rest of the tool surface has no CLI form, on purpose: it is stateful across
calls and there is no session to hold that state in from a shell.
Prompt patterns
Say what evidence you want back, and hand over what the server cannot infer: the include paths, the defines, and which function is the target. The left column is what you type; the middle is what a well-behaved agent does with it; the right is the trap that makes the obvious call the wrong one.
| Say | Call | Trap |
|---|---|---|
"Check foo.c for runtime errors and prove its contracts; it builds with -Iinclude -DNDEBUG. Target bar. Tell me what was left unchecked." |
check({files:["foo.c"], function:"bar", include_paths:["include"], defines:["NDEBUG"]}) |
check reloads the project, so it needs the real build flags. Without them Frama-C parses a different program, or none |
| "Give me every goal and alarm, not the first few." | check({..., detail:"full"}) |
The default is summary. full runs to hundreds of kilobytes on a real file, and verdict and incomplete[] are computed from the complete data either way |
| "Frama-C cannot parse this. Reproduce the compiler configuration; do not delete code to make it parse." | reload_project({files, include_paths, defines, force_includes, machdep}) |
force_includes supplies declarations Frama-C lacks. A define that erases the call site parses, and then proves the wrong program |
"What can n hold at foo.c:42?" |
context({want:["marker_at"], file:"foo.c", line:42}) → context({want:["eva_value"], marker}) |
Needs EVA to have run. Which marker comes back follows the position, not the intent: a declaration line answers with the variable's #v, so read marker_kind before passing it on |
| "Why might line 42 overflow? Show the values, the callers, and the annotations in force." | get_wp_goals({want:["alarms"]}) → get_wp_goals({want:["investigation"], marker:"#p10", depth:"deep"}) |
investigation takes the property marker off the alarm row. depth defaults to normal, which omits the annotations |
"List everything this run did not establish for bar." |
get_wp_goals({want:["alarms","goals"], function:"bar", status:"unproved"}) |
unproved is every status other than valid. A status that is neither a Frama-C name nor one this run produced is an error, so a typo cannot read as proved |
| "Why is that goal not proved? Show the hypotheses WP had." | get_wp_goals({want:["vc"], function:"bar"}) |
The sequent is per function, and vc requires function |
"Show me bar as Frama-C sees it, with my contract read back." |
context({want:["contract_context","loop_effects"], function:"bar"}) |
The read-back route for annotations you injected: type-checked, macros expanded, as WP will use them |
| "I have no annotations yet. What does the code itself determine?" | propose_annotations({function:"bar"}) → inject_all_annotations({function:"bar", dry_run:true, annotations:[...]}) |
Frames only, each already type-checked against the AST. The predicates that make a proof go through are under not_proposed, named rather than guessed |
| "Type-check this ACSL against the real AST but change nothing." | inject_all_annotations({function:"bar", dry_run:true, annotations:[...]}) |
Invariants, asserts, assigns, ghost code and lemmas all inject on main. requires and ensures are the exception, refused there whatever dry_run says |
"Try requiring n >= 0 without touching the main project." |
create_sandbox({function:"bar", experiment_id:"exp42"}) → inject_all_annotations({sandbox_name:"exp42:bar", annotations:[...]}) → run_wp({functions:["exp42:bar"]}) |
Contracts belong to whoever reviews the source, so main refuses them and the sandbox is where one gets tried. Merge back explicitly |
"Prove bar now, and tell me what my last change actually bought." |
run_wp({functions:["bar"], cache:"None"}) → get_wp_goals({function:"bar", since:"<earlier receipt sha256>"}) |
-wp-cache defaults to update, so a valid verdict may be replayed rather than computed. progress.fraction_delta measures the goals both runs share, so the ones your edit added show up under appeared instead. since requires the same function scope and only names receipts from this session |
"Prove the ready functions, one bounded batch at a time, then record what bar assumed." |
run_wp({functions:["bar"], retry_unproved:true}) → store_function_conclusion({function:"bar", status:"verified", proof_receipt_sha256, wp_summary}) → list({kind:"conclusions", function:"bar"}) |
WP's budget is per call, so an oversized batch returns nothing at all. verified is refused unless the receipt's goals are all valid and their count matches wp_summary. Past 200 goals run_wp trims its receipt object, so pass its sha256 as proof_receipt_sha256 rather than the object |
| "Verify the file bottom up and tell me what to do next." | verify_program_step({lock_project:false}) |
The lock defaults on and blocks every later run_wp on main |
| "Does it actually break when it runs?" | run_e_acsl({use_current_ast:true, args:[...]}) |
Compiles and executes the code with your privileges; trusted source only. Without use_current_ast it runs the files on disk, which do not carry this session's annotations |
| "Write out the annotated source." | context({want:["source"], output:"out/annotated.c"}) |
Whole program, every contract and generated RTE assert. The path must stay inside the working directory |
| "Why did that tool fail?" | self_check({canary:true}) |
Versions, provers, which requests answer. canary adds about 30s proving the backend still tells a bundled bug from its fix |
The WP memory model is process state. Frama-C takes some changes within one
process and not others, so a change that aborts reports what it changed from
and points at reload_project.
Ask for a verdict rather than a summary. check reports proved only when
incomplete[] is empty, so "no alarms were reported" and "everything was
checked" stay distinguishable. See docs/agent-playbook.md
for the shortest reliable call order for each workflow, and
docs/writing-acsl.md for what to write when a goal will
not close, keyed to the finding categories and incomplete[] codes.
Tools
The server exposes the following tool groups:
| Domain | Tools | Purpose |
|---|---|---|
| Project | reload_project, list, context, self_check, parse_surface |
Load source, inspect declarations, navigate call relationships, report server capabilities, and measure how much of a file set Frama-C can parse at all |
| Concurrency | analyze_concurrency |
Screen source text for concurrent events, lock order, and race and deadlock candidates. Level-0 syntax: candidates are never verdicts, and an absent candidate is not one either |
| EVA/WP | check, run_wp, get_wp_goals, proof_coverage, run_e_acsl |
Run verification, read its conclusions, report stored proof coverage, and execute runtime counterexamples |
| Annotations | inject_all_annotations, propose_annotations |
Dry-run validate and inject ACSL annotations, and propose the frame conditions the code determines |
| Sandbox | create_sandbox, delete_sandbox |
Isolate annotation experiments |
| Orchestration | verify_program_step |
Run bottom-up verification steps |
| State | store_function_conclusion |
Persist verification conclusions |
run_e_acslcompiles the loaded source and runs the resulting binary with your privileges. Every other tool only analyzes. Do not point it at C source you do not trust, and note that an agent reading untrusted source can be steered into calling it.
proof_coverage {} measures defined loaded functions against their stored
conclusions. Use proof_coverage {verify_profile: "target", detail: "full"}
to measure the function set declared by a build-system target. It splits its
valid WP goals into fresh_valid and cached_valid, the latter being verdicts
WP replayed from its cache rather than computed on the run that produced the
receipt, and it counts a receipt shared by several functions once.
It proves only the obligations generated by the ACSL/RTE/WP configuration that
produced those receipts; omitted requirements are not coverage. It reads WP
only, so a complete verdict is a statement about proof obligations rather
than about every analysis this server can run, and it does not inspect whether
a covered function declares an assigns clause, because the specs a
conclusion carries are supplied by the caller and may be absent for a function
that has one.
The goal denominator holds every in-scope receipt, not only the ones behind a covered function, so obligations that were attempted and did not discharge are counted rather than dropped. Storing a verified conclusion already requires every goal in its receipt to be valid, so a denominator drawn from covered functions alone could only ever read 100 percent.
A function is uncovered, with the reason named in its row, whenever anything at
all disqualifies it: no stored conclusion (missing_conclusion), a stored
conclusion that is not verified, which is reported under its own status name,
or a verified one with no receipt (missing_proof_receipt). Beyond those, when
its conclusion belongs to another verify_profile (different_verify_profile)
or no longer fits a re-registered one (profile_evidence_mismatch), when the
receipt was produced over a different file set or under different preprocessor
settings (different_project, which is what makes it safe to keep conclusions
across a reload_project that switches projects), when its callee contracts or
proof environment have gone stale, when a source file its
receipt hashed has since changed on disk (stale_source), when the receipt does
not name this function among the ones WP ran over
(receipt_does_not_prove_function), when the run was restricted by prop and so
attempted only part of the function (proved_under_a_goal_filter), when a
verify_profile names a function this project does not define, whether it is
absent or only declared (not_defined_in_project), or when a callee inside the
measured set is itself uncovered (unverified_callee, propagated through the
call chain).
docs/agent-playbook.md carries the full table of reasons and what each one
asks you to do about it.
A file the receipt named that cannot be read now, such as one from a deleted
sandbox, a path that is not a regular file, or a bare relative name with no
directory on it, which would otherwise resolve against the server's working
directory, is listed under unchecked_sources rather than judged either way. A
relative path that keeps its directory is resolved, since that is the path
reload_project was given and the one Frama-C itself was launched with.
A receipt records the whole loaded file set rather than the one file its
function lives in, so editing any loaded source marks every stored conclusion
stale_source, not only the conclusions about that file. That is the honest
reading, since WP proves a function against the AST of all loaded files and a
receipt carries no per-function source attribution, but expect one edit to turn
the whole report red. The edited paths are listed once for the whole
report under changed_sources, as the unreadable ones are under
unchecked_sources, with each row carrying only its own counts.
A function this project declares without defining sits outside both
denominators, named under scope.declared_not_defined, unless a
verify_profile names it as a target. Then it stays in the denominator as
not_defined_in_project, because a target does not stop declaring a function
when the file defining it was not loaded, and excusing it would let a profile
report complete on whichever of its functions happened to be present.
The rest of this section covers the parameters whose behavior is not obvious from the tool schema.
Input constraints
Identifiers that become directory names, store_function_conclusion {function}
and create_sandbox {experiment_id}, are restricted to [A-Za-z0-9_-] so they
cannot escape .frama-c-mcp/ or the sandbox root.
context {want: ["source"], output} is the only tool that writes a file the
caller names, and the path must resolve inside the working directory. An
absolute path elsewhere, a .. that climbs out, and a symlink inside the tree
that points out of it are all refused.
run_e_acsl {tool} names the E-ACSL wrapper, not an arbitrary executable: it
must be e-acsl-gcc or e-acsl-gcc.sh, resolved through PATH. Both names
exist because installs differ.
Frama-C MCP questions
Does it support Windows?
No, there is no Windows build because the transport uses Unix sockets and Frama-C does not target Windows.
How does the sandboxing work?
The server extracts a function with its dependencies into a temporary C file and starts a separate Frama-C process to allow iterative annotation testing without mutating the main project.
Can I use this in a CI pipeline?
Yes, the check subcommand is designed for CI and allows running the same code path as the check tool without an agent.