cmake-build-model
An MCP server that lets AI assistants read the build model of already-configured CMake projects (read-only) to answer questions about targets, compilation, dependencies, cache, toolchains and inputs.
Discover projects and builds —
list_projectsfinds source projects and build directories under the workspace roots (generator, build type, File API availability/staleness);register_build_diradds build directories outside the roots.Inspect presets —
list_presetslists configure/build presets fromCMakePresets.json/CMakeUserPresets.jsonwith resolved binary directories.Get a project overview —
get_project_summaryreports CMake version, generator, configurations, theproject()hierarchy and targets grouped by type.Explore targets —
list_targetsfilters by type, name (substring/glob/regex), project or directory;get_targetgives artifacts, definition site, dependencies, link/archive fragments, install destinations, per-compile-group flags/defines/includes/language standard, sources and optional backtraces.Trace dependencies —
get_target_dependenciesreturns direct or transitive dependencies/dependents plus an adjacency list.See how a file is built —
find_file_targetsfinds which targets in which build dirs/configurations compile a file, combining File API settings with matchingcompile_commands.jsonentries (headers fall back to include-directory matches).Read exact compiler invocations —
get_compile_commandsreturns directory, arguments and original command, filtered by file, path pattern, target or configuration.Query configuration and toolchain —
get_cache_variables(with advanced/internal options),get_toolchains(compilers per language with implicit include/link dirs),get_cmake_inputs(files CMake read during configure, glob dependencies, external files/CMake modules).Multi-build and multi-config aware — accepts a
buildDir(absolute or workspace-relative; a source dir with a single build dir also works) and aconfigurationfor multi-config generators, searching all known build directories when omitted.
Provides read-only tools for querying CMake project build models via the CMake File API and compile_commands.json, including targets, sources, compile flags, include directories, defines, language standards, dependencies, artifacts, install rules, cache variables, toolchains, and exact compiler invocations across multiple build directories.
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., "@cmake-build-model how is src/main.cpp compiled in the release build?"
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.
cmake-build-model-mcp
An MCP server that lets AI assistants query the build model of CMake
projects — targets, sources, compile flags, include directories, defines, language standards, dependencies,
artifacts, install rules, cache variables and toolchains — using the
CMake File API, plus the exact compiler
invocations from compile_commands.json. It also queries the ctest model written into CTestTestfile.cmake
(names, labels, fixtures, dependencies) and the results in Test.xml, so a large suite can be filtered without
pasting those files into the conversation.
Point it at one or more build directories that already contain a File API reply (for example build-debug
and build-release, or a multi-config build). It can answer questions like "how is this file compiled?"
across every build directory it was given.
The server is read-only: it never runs CMake, never executes tests, and never writes into build directories,
except that preview_test_run with engine: "ctest" runs ctest --show-only (a dry run). That updates
Testing/Temporary/LastTest.log and does not run test executables. Everything else only reads what a previous
configure or ctest -T Test left behind.
Prerequisites for build directories
Each build directory must already contain a File API reply with at least the codemodel object. Create the
query files before configuring (or re-configure after creating them):
mkdir -p build/.cmake/api/v1/query
touch build/.cmake/api/v1/query/{codemodel-v2,cache-v2,cmakeFiles-v1,toolchains-v1}
cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ONcodemodel-v2is required;cache-v2,cmakeFiles-v1andtoolchains-v1enable the cache, inputs / staleness and toolchain tools.Replies requested by other clients (e.g. VS Code CMake Tools or CLion) are used as well, so build directories managed by an IDE usually work as-is.
CMAKE_EXPORT_COMPILE_COMMANDS=ON(Makefile and Ninja generators) writescompile_commands.json, whichfind_file_targetsandget_compile_commandsread. Without it, everything else still works.
Related MCP server: fw-context-mcp
How it works
Build directories. Each directory passed on the command line is recorded.
CMakeCache.txtin that directory supplies the source directory, generator and build type.Reply. The newest
.cmake/api/v1/reply/index-*.jsonis read; objects are loaded lazily and cached until the reply index changes, so re-configuring outside the server is picked up automatically.Compile commands.
<buildDir>/compile_commands.jsonis loaded (and re-loaded when it changes) and indexed by source file. Entries are attributed to targets and configurations through their object file path (CMakeFiles/<target>.dir/[<config>/]...).Staleness. Using the
cmakeFilesobject, the server reports when aCMakeLists.txtor included.cmakefile has been modified since the last configure.
Tools
Tool | Purpose |
| The build directories given at startup, with source directory, generator, build type, File API status (codemodel present, stale, modified inputs) and |
| CMake version, generator, configurations, |
| Targets filtered by type, name (substring / glob / |
| Everything about one target: definition site, artifacts, dependencies, compile groups (flags, defines, includes, standard, PCH), link/archive fragments, install destinations, sources, optional backtraces. |
| Direct or transitive dependencies or dependents of a target. |
| Which targets compile a file (in every given build directory and configuration), with the File API compile settings and the matching |
| Exact entries of |
| Cache entries with type, value, help string; filterable. |
| Compilers per language with implicit include/link directories. |
| Files CMake read during configure, glob dependencies, and inputs modified since then. |
| Tests from |
| One test: command, properties, labels, fixtures, dependencies, backtrace. |
| Each label and how many tests have it. |
| Each fixture and the tests that set it up, require it, or clean it up. |
|
|
| Dry run of a ctest selection ( |
| Counts and timing from |
| Per-test status, time, and exit code. No stdout. Accepts the same selection as |
| One test's measurements and stdout, truncated to |
list_build_dirs includes a ctest object: hasTestfile, and testXml when Testing/TAG points at a Test.xml.
Test selection
preview_test_run and list_test_results take ctest's filters:
include/excludeare-R/-E: one regex each, unanchored and case-sensitive.^and$anchor.|ORs names.labels/excludeLabelsare repeatable-L/-LE. Every regex must match some label on the test (AND). Puttue|wedin one entry to OR labels.A match does not pull
DEPENDStests into the set. It does pullFIXTURES_SETUPandFIXTURES_CLEANUPfor fixtures a selected test requires, unless-FA,-FS, or-FCsays otherwise. Disabled matches are listed and do not pull fixtures.engine: "index"(the default) parsesCTestTestfile.cmakeand does not run ctest.{and}are literal.\d,\b, lookaheads, and lazy quantifiers are rejected because ctest'sstring(REGEX)engine does not have them.engine: "ctest"runsctest --show-only=json-v1with the same flags. Use it when a command still contains a generator expression. Exact name lists need CMake 3.29+ (--tests-from-file).explain: trueadds up to 20 names for each reason a test was left out.
Test.xml is the file written by ctest -T Test (the dashboard test step), not by a plain ctest invocation. Pass testXml to read a copy from somewhere else. The result index keeps status and timing; stdout is read only for get_test_result.
Most tools accept a buildDir argument: the absolute path given at startup, or a unique suffix of one
(build-debug, app/build-debug). Omit it when the server was started with a single build directory.
File paths may be absolute, relative to the working directory, or relative to a build's source directory
when that match is unique. Multi-config generators (Visual Studio, Xcode, Ninja Multi-Config) are supported
through the configuration argument.
Example find_file_targets result:
{
"file": "/src/app/tools/main.cpp",
"matches": [
{
"buildDir": "/src/app/build",
"target": "app_cli",
"targetType": "EXECUTABLE",
"matchedBy": "source",
"compileGroup": {
"language": "CXX",
"languageStandard": "20",
"compileFlags": ["-std=gnu++20", "-Wall"],
"defines": ["CORE_VERSION=3"],
"includes": [{ "path": "/src/app/include" }]
},
"compileCommands": [
{
"file": "/src/app/tools/main.cpp",
"directory": "/src/app/build/tools",
"output": "tools/CMakeFiles/app_cli.dir/main.cpp.o",
"arguments": ["/usr/bin/c++", "-DCORE_VERSION=3", "-I/src/app/include", "-std=gnu++20", "-Wall",
"-o", "CMakeFiles/app_cli.dir/main.cpp.o", "-c", "/src/app/tools/main.cpp"],
"command": "/usr/bin/c++ -DCORE_VERSION=3 -I/src/app/include -std=gnu++20 -Wall -o CMakeFiles/app_cli.dir/main.cpp.o -c /src/app/tools/main.cpp"
}
]
}
]
}Requirements
Node.js 18+
Build directories produced by CMake 3.14+ (3.20+ for
toolchains; newer versions add fields such aslanguageStandard). CMake itself does not need to be installed where the server runs.
Installation
git clone https://github.com/pkp124/cmake-build-model-mcp.git
cd cmake-build-model-mcp
npm install # also builds dist/Configuration
The server speaks MCP over stdio.
cmake-build-model-mcp [options] <build-dir>...
--build-dir <dir> Build directory that already contains a File API reply (repeatable).
Positional arguments are build directories too.Cursor (.cursor/mcp.json)
{
"mcpServers": {
"cmake-build-model": {
"command": "node",
"args": ["/path/to/cmake-build-model-mcp/dist/index.js", "/path/to/build"]
}
}
}Pass every build directory you want to query (debug and release, or several projects).
Claude Desktop / Claude Code
{
"mcpServers": {
"cmake-build-model": {
"command": "node",
"args": ["/path/to/cmake-build-model-mcp/dist/index.js", "/path/to/build"]
}
}
}claude mcp add cmake-build-model -- node /path/to/cmake-build-model-mcp/dist/index.js /path/to/buildVS Code (.vscode/mcp.json)
{
"servers": {
"cmake-build-model": {
"type": "stdio",
"command": "node",
"args": ["/path/to/cmake-build-model-mcp/dist/index.js", "/path/to/build"]
}
}
}Notes and limitations
INTERFACElibraries only appear in the codemodel when they have sources (a CMake File API rule).compile_commands.jsonis not produced by the Visual Studio and Xcode generators; for those, use the File API compile groups returned byget_target/find_file_targets.Test parsing understands the
CTestTestfile.cmakefiles CMake generates (add_test,set_tests_properties,set_directory_properties,subdirs, andif(CTEST_CONFIGURATION_TYPE MATCHES ...)). Hand-written logic (foreach,include, otherifconditions) is skipped and reported inwarnings.Directory
LABELSare unioned with each test's own labels. Generator expressions are left as written unlesspreview_test_runis called withengine: "ctest".
Development
npm run build # compile TypeScript to dist/
npm test # build + unit and end-to-end tests (needs cmake and a C/C++ compiler; ninja optional)The end-to-end tests copy test/fixtures/workspace (two independent projects) into a temporary directory,
configure several build directories with File API queries (the test harness runs CMake, the server never
does), including a Ninja Multi-Config one when ninja is available, and drive the compiled server over
stdio with the MCP SDK client, passing those build directories on the command line.
License
MIT
Available Tools
12 toolsfind_file_targetsFind how a file is builtARead-only
Finds which targets (in which build directories and configurations) compile a given source file, and returns the effective language, standard, flags, defines and include directories from the File API together with the exact compiler command(s) from the build directory's compile_commands.json. For headers not listed as sources, returns targets whose include directories contain the file. Searches all known build directories unless buildDir is given.
Inputs: file (required), buildDir, configuration, includeBacktraces.
get_cache_variablesGet CMake cache variablesARead-only
Returns CMake cache entries (name, type, value, help string), optionally filtered by name. Advanced entries are hidden unless includeAdvanced is set or a filter is given.
Inputs: filter, buildDir, includeAdvanced, includeInternal.
get_cmake_inputsGet CMake input filesBRead-only
Lists the files CMake read during configuration (CMakeLists.txt, included .cmake modules, configure_file inputs, etc.) and glob-dependent file lists.
Inputs: buildDir, includeExternal, includeCMakeModules.
get_compile_commandsGet compile commandsARead-only
Reads the exact compiler invocations from compile_commands.json in a build directory, filtered by file, path pattern, target and/or configuration. When file is given without buildDir, every build directory of the workspace that compiles the file is searched. Each entry has the working directory, the argument list, the original command string (when the database uses command) and the output file.
Inputs: file, limit, filter, target, +2 more.
get_project_summarySummarize a build directory's modelARead-only
High-level overview of a configured build directory: CMake version, generator, configurations, the project() hierarchy and target names grouped by type.
Inputs: buildDir, configuration.
get_targetGet target detailsBRead-only
Full details of one target: artifacts, where it is defined, dependencies, link/archive command fragments, install destinations, and per compile group the language standard, flags, defines and include directories, plus its source files.
Inputs: target (required), buildDir, maxSources, configuration, +2 more.
get_target_dependenciesGet target dependency graphARead-only
Returns the targets a target depends on (dependencies) or the targets depending on it (dependents), directly or transitively, including an adjacency list for the transitive graph.
Inputs: target (required), buildDir, direction, transitive, +1 more.
get_toolchainsGet toolchainsBRead-only
Returns the compilers used per language (path, id, version, target) including implicit include and link directories.
Inputs: buildDir.
list_presetsList CMake presetsBRead-only
Lists the configure and build presets from CMakePresets.json / CMakeUserPresets.json of a source directory, with resolved binary directories.
Inputs: sourceDir (required).
list_projectsList CMake projects and build directoriesBRead-only
Lists top-level CMake source projects and build directories found under the workspace roots, including which source directory each build directory belongs to, its generator/build type and whether a File API reply is available and up to date.
Inputs: rescan.
list_targetsList targetsBRead-only
Lists build targets with type, project, defining directory, artifacts and languages.
Inputs: name, type, project, buildDir, +2 more.
register_build_dirRegister a build directoryARead-only
Adds an existing CMake build directory (one containing CMakeCache.txt) that lies outside the workspace roots, e.g. /tmp/build-foo, so the other tools can query it.
Inputs: buildDir (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Tools are mostly distinct, but find_file_targets and get_compile_commands overlap in returning compiler commands for a file, and get_target includes dependency information that get_target_dependencies also provides. Descriptions mitigate confusion, but the boundaries are not perfectly clean.
Consistent snake_case verb_noun pattern throughout (list_, get_, find_, register_), with no mixed conventions or vague verbs.
12 tools is well-scoped for a CMake build model inspector; each tool covers a distinct aspect such as projects, targets, dependencies, cache, toolchains, and inputs without redundancy.
The core inspection surface is comprehensive, covering projects, targets, dependencies, compile commands, cache variables, toolchains, and CMake inputs. Minor gaps include no tool to unregister a build directory or retrieve full preset details beyond resolved binary directories.
Maintenance
Related MCP Connectors
Build, test and cache insights for Xcode, Gradle and Bazel projects, for coding agents.
Read-only AI project discovery, verification, comparison, shortlisting, and stack planning.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Ask your AI about construction and ad-platform data. Read-only on your systems, never writes to them
Related MCP Servers
- AlicenseAqualityDmaintenanceExposes codebase analysis data, including module structures, dependencies, and AI-generated insights, to AI assistants via the Model Context Protocol. It enables users to query project architecture and search for specific code entities across analyzed projects.1019 npm1MIT
- AlicenseAqualityAmaintenanceExposes tools for AI assistants to query a persistent SQLite+FTS5 index of C/C++ symbols parsed from real build commands, enabling sub-millisecond lookup, full-text search, and natural-language explanation without hallucination.37509 PyPI10MIT
- AlicenseAqualityFmaintenanceIndexes Unreal Engine project C++ source, config files, dependencies, gameplay tags, replication, asset references, and log categories into a SQLite database and exposes tools for AI assistants to query structural and config info.17MIT
- AlicenseAqualityDmaintenanceProvides C++ code intelligence tools for AI agents via the Model Context Protocol, enabling symbol navigation, type information, and diagnostics.950Mozilla Public 2.0