sagemath-mcp
Provides graph-theoretic analysis tools powered by SageMath, including matching covered graphs, bricks, essentially 4-edge-connected graphs, near-bipartiteness, edge invariants, cyclic edge cuts, and named graph identification.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sagemath-mcp Is Ks?GOgSOpDL? essentially 4-edge-connected?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sagemath-mcp
An MCP server that answers structural questions about graphs using SageMath — aimed at matching covered graphs, bricks and snarks.
Ask an agent "is Ks?GOgSOpDL? essentially 4-edge-connected?" or "does the cubeplex have
quasi-b-invariant edges?" and it calls a tool instead of guessing.
> Is Ks?GOgSOpDL? efec or not?
is_efec(graph="Ks?GOgSOpDL?") -> {"is_efec": true, "order": 12, "size": 18, ...}
Yes. It is essentially 4-edge-connected: no three pairwise non-adjacent edges
disconnect it. It is also a cubic brick, and near-bipartite.Requirements
SageMath 10.x (developed against 10.6). Not a pip dependency — install it separately.
Python 3.10+ for the server itself.
On Windows, Sage runs inside WSL and the server finds it there automatically.
Related MCP server: genpark-graph-dijkstra-astar-pathfinder-skill
Install
uvx sagemath-mcp # no install
pipx install sagemath-mcp # or a persistent installFrom a clone:
pip install -e ".[test]"Register with an MCP client
{
"mcpServers": {
"sagemath": { "command": "uvx", "args": ["sagemath-mcp"] }
}
}With Claude Code: claude mcp add sagemath -- uvx sagemath-mcp.
Finding SageMath
The server resolves Sage in this order, and reports what it tried if none works:
SAGE_MCP_BIN— a full path to thesageexecutable. On Windows a path beginning with/is understood as being inside WSL. Force the choice withSAGE_MCP_USE_WSL=1or=0.sageonPATH.On Windows only: inside WSL, first
command -v sage, then the usual conda and system locations.SAGE_MCP_WSL_DISTROpicks a specific distro.
A cold Sage start costs seconds, so the server keeps one Sage process alive and talks JSON to it. The first tool call pays the startup; later calls return in milliseconds.
Tools
Every graph argument takes either a graph6 string or a name from the registry
(cubeplex, petersen, blanusa 1, ...). Answers are structured, echo the graph analysed,
and carry a witness whenever one exists.
Tool | Answers |
| order, size, connectivity, girth, planarity, bipartiteness, edges |
| everything at once — the best default for open-ended questions |
| connected, and every edge in some perfect matching |
|
|
| 3-connected and bicritical, reporting which half fails |
| essentially 4-edge-connected, with the disconnecting triple when not |
| cubic + efec + brick, naming the first failed check |
| with the removable edge pair as witness |
| classify one edge of a brick, with the barriers of |
| the full b-invariant / quasi-b-invariant split of a brick |
| does this brick have quasi-b-invariant edges, and which |
| is there a cyclic edge cut of size exactly |
| the smallest such |
| the registry |
| is this graph6 string a known graph, up to isomorphism |
| escape hatch: run arbitrary Sage code |
has_cyclic_edge_cut and cyclic_edge_connectivity search all 2^(n-1) vertex bipartitions.
They refuse graphs above max_order (default 24) rather than hanging; raise it to search anyway.
Named graphs
k4, k33, cube, petersen, cubeplex, twinplex, tietze, heawood, moebius_kantor,
blanusa_first_snark, blanusa_second_snark, pappus, near_bipartite_brick_18,
snark_18_four_quasi, snark_18_two_quasi, desargues, dodecahedron, flower_snark_5,
snark_20_zero_quasi, cubic_brick_24, mcgee, nauru, coxeter, double_star_snark,
tutte_coxeter, szekeres_snark, watkins_snark.
Names are matched loosely, so Blanusa-1, blanusa 1 and blanusa_first_snark are the same
graph. Add your own by editing src/sagemath_mcp/named_graphs.json, or regenerate the file with
sage -python scripts/build_registry.py.
Glossary
Matching covered — connected, with every edge in some perfect matching.
Bicritical —
G - u - vhas a perfect matching for every pair of distinct vertices.Brick — a 3-connected bicritical graph. Bricks and braces are the building blocks of the tight cut decomposition of matching covered graphs.
Barrier — a vertex set
Bwitho(G - B) = |B|odd components; nontrivial means|B| > 1.Essentially 4-edge-connected (efec) — no three pairwise non-adjacent edges disconnect the graph, so its only small edge cuts are the trivial ones around a vertex.
Near-bipartite — some pair of non-adjacent edges can be removed to leave a bipartite matching covered graph.
b-invariant edge — an edge
eof a brickGsuch thatG - eretains the barrier structure the theory requires; an edge that fails this is quasi-b-invariant. Every brick other thanK₄,C̄₆and the Petersen graph has a b-invariant edge — in the Petersen graph all fifteen edges are quasi-b-invariant, which this server reproduces.Cyclic k-edge-cut — a vertex bipartition with exactly
kcrossing edges where neither side induces a forest.
Tests
pytest # registry tests run anywhere; Sage tests skip without Sage
pytest -m "not sage" # registry onlyThe Sage-dependent tests check values recorded in the research notebooks this server was extracted from — the cubeplex's properties, cyclic edge connectivities of 5 and 6, and the exact quasi-b-invariant edges and barriers of an 18-vertex snark.
License
MIT.
Available Tools
16 toolsanalyzeAnalyzeA
Run every check at once and return one summary of the graph.
Cheap checks first; checks that do not apply are skipped with a reason (b-invariance needs a brick, for instance). Prefer this for open-ended questions such as "what can you tell me about this graph?" or "is this a near-bipartite essentially-4-edge-connected cubic brick?".
Inputs: graph (required), kmax, max_order. Returns: object
classify_edgesClassify EdgesA
Split every edge of a brick into b-invariant and quasi-b-invariant.
Each quasi-b-invariant edge is reported with the two nontrivial barriers of G - e. Only defined for bricks.
Inputs: graph (required). Returns: object
cyclic_edge_connectivityCyclic Edge ConnectivityA
Smallest k in [kmin, kmax] for which the graph has a cyclic k-edge-cut.
That value is the graph's cyclic edge connectivity when it falls inside the search range; a null answer means none was found and kmax should be raised.
Inputs: graph (required), kmax, kmin, max_order. Returns: object
graph_infoGraph InfoA
Basic invariants of a graph: order, size, connectivity, girth, edges.
Use this first when you need to know what a graph is before asking sharper questions about it.
Inputs: graph (required). Returns: object
has_cyclic_edge_cutHas Cyclic Edge CutA
Does the graph have a cyclic edge cut of size exactly k?
That is, a vertex bipartition (S, T) with exactly k crossing edges where neither induced subgraph is a forest. Both shores come back as a witness.
The search is exhaustive over 2^(n-1) bipartitions, so it is refused above max_order vertices; raise max_order to search anyway.
Inputs: k (required), graph (required), max_order. Returns: object
has_qbinv_edgesHas Qbinv EdgesB
Does this brick have any quasi-b-invariant edges?
Returns the count and the edges themselves.
Inputs: graph (required). Returns: object
identify_graphIdentify GraphA
Is this graph one of the registry's named graphs, up to isomorphism?
Useful for a bare graph6 string that may be a relabelling of a well-known graph.
Inputs: graph (required). Returns: object
is_bicriticalIs BicriticalA
Is the graph bicritical: does G - u - v have a perfect matching for every pair of distinct vertices u, v?
Inputs: graph (required). Returns: object
is_brickIs BrickA
Is the graph a brick: 3-connected and bicritical?
Reports the two conditions separately, so a negative answer says which one failed.
Inputs: graph (required). Returns: object
is_edge_binvariantIs Edge BinvariantA
Is the edge (u, v) of a brick b-invariant, or quasi-b-invariant?
Only defined for bricks. Also returns the nontrivial barriers of G - e.
Inputs: u (required), v (required), graph (required). Returns: object
is_efecIs EfecA
Is the graph essentially 4-edge-connected (efec)?
True when no three pairwise non-adjacent edges disconnect the graph. When False, the answer includes the disconnecting triple that witnesses it.
Inputs: graph (required). Returns: object
is_efec_cubic_brickIs Efec Cubic BrickA
Is the graph an essentially-4-edge-connected cubic brick?
Checks cubic, then essentially 4-edge-connected, then brick, stopping at the first failure and naming it in "failed_check".
Inputs: graph (required). Returns: object
is_matching_coveredIs Matching CoveredA
Is the graph matching covered: connected, with every edge in some perfect matching?
Inputs: graph (required). Returns: object
is_near_bipartiteIs Near BipartiteA
Is the graph near-bipartite?
True when some pair of non-adjacent edges can be removed to leave a bipartite matching covered graph; that pair comes back as the witness.
Inputs: graph (required). Returns: object
list_named_graphsList Named GraphsA
Every graph in the registry that can be referred to by name.
Returns name, aliases, order, size, graph6 string and a short note for each.
Inputs: no named parameters. Returns: result
run_sageRun SageA
Run arbitrary SageMath code and return its stdout, stderr and exit status.
An escape hatch for questions the typed tools do not cover. Print what you want to see; nothing is returned implicitly. Runs in a fresh Sage process, so it cannot see or disturb state from the other tools.
Inputs: code (required), timeout. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
The tools cover overlapping graph-theoretic concepts (e.g., is_efec, is_efec_cubic_brick, has_cyclic_edge_cut, cyclic_edge_connectivity all relate to edge connectivity), which may cause some misselection. However, each tool has a distinct focus and the descriptions are detailed enough to clarify most differences.
Most tools follow a clear snake_case pattern with prefixes like is_, has_, classify_, list_, identify_, run_. A few outliers like cyclic_edge_connectivity and graph_info are noun phrases rather than verb phrases, creating a slight inconsistency but not a major one.
16 tools is slightly above the ideal 3-15 range but still reasonable for a specialized graph analysis server. The tools cover a broad set of related properties without being excessively redundant.
The tool set covers many graph properties and includes run_sage for arbitrary computations, making it functionally complete. However, there are some specific checks (e.g., near-bipartite, brick, efec) that are covered, but not all possible graph invariants, so it is not exhaustive.
Maintenance
Related MCP Connectors
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Repository knowledge graph MCP server for codebase understanding and debugging.
Query your own knowledge graph from any MCP client. The graph lives in a database you own.
Unofficial Math.js MCP — wraps the mathjs.org API (free, no auth)
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceExposes the full SageMath computer algebra system to LLM clients through MCP tools for symbolic mathematics, solving, calculus, plotting, and number theory.73 npm1Creative Commons Zero v1.0 Universal
- AlicenseNot gradedqualityBmaintenanceEnables agents to compute shortest paths with Dijkstra and A*, resolve DAG dependencies, solve maximum flow, build minimum spanning trees, and rank graph centrality using JSON-RPC MCP tools.7MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to compute shortest paths, topological dependency order, maximum flow and minimum-cut bottlenecks, minimum spanning trees, and PageRank centrality over weighted graphs for routing and execution planning. It exposes these graph-analysis capabilities as MCP tools through a zero-dependency Python server.7MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables agents to compute shortest paths, topological orderings, maximum flow and minimum cut bottlenecks, minimum spanning trees, and centrality rankings for graph-based multi-agent routing. It runs as a zero-dependency MCP server using standard Python libraries.MIT