Skip to content
Back to search

mcp-cpp

MCP server tailored to work with large C/C++ codebases

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mpsm--mcp-cpp/badge.svg)](/listings/mpsm--mcp-cpp)

HTML

<a href="/listings/mpsm--mcp-cpp"><img src="/api/listings/mpsm--mcp-cpp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install from Crates.io (Recommended)

# Install directly from the registry
cargo install mcp-cpp-server

# The binary will be available in your cargo bin directory
# (usually ~/.cargo/bin/mcp-cpp-server)

Install from Source

# Clone the repository
git clone https://github.com/mpsm/mcp-cpp.git
cd mcp-cpp

# Install from source
cargo install --path .

# The binary will be available in your cargo bin directory
# (usually ~/.cargo/bin/mcp-cpp-server)

Docker Installation

# Build the Docker image
docker build -t mcp-cpp-server .

# Run with your C++ project mounted
docker run -i --rm -v /path/to/your/cpp-project:/workspace mcp-cpp-server

The Docker image includes: - mcp-cpp-server binary - clangd-20 for C++ semantic analysis - Minimal Ubuntu-based runtime

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 388 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # C++ MCP Server
  2. [![CI](https://github.com/mpsm/mcp-cpp/actions/workflows/ci.yml/badge.svg)](https://github.com/mpsm/mcp-cpp/actions/workflows/ci.yml)
  3. [![License](https://img.shields.io/github/license/mpsm/mcp-cpp)](LICENSE)
  4. [![Rust](https://img.shields.io/badge/rust-2024%2B-orange.svg)](https://www.rust-lang.org)
  5. [![Crates.io](https://img.shields.io/crates/v/mcp-cpp-server?label=crates.io)](https://crates.io/crates/mcp-cpp-server)
  6. A Model Context Protocol (MCP) server that provides C++ code analysis capabilities through clangd LSP integration. Enables AI agents to work with C++ codebases using semantic understanding similar to modern IDEs.
  7. ## Why This MCP Server?
  8. Modern C++ development relies heavily on advanced tooling to navigate complex codebases with preprocessor macros, template instantiations, and intricate inheritance hierarchies. While humans use IntelliSense-powered IDEs to understand these complexities, most AI agents rely on text-only browsing.
  9. This MCP server bridges that gap by providing AI agents with semantic analysis capabilities similar to what developers experience in modern IDEs. Unlike generic LSP MCP implementations, this server focuses specifically on C++ workflows.
  10. The server can handle multiple C++ projects simultaneously, which is particularly useful for complex scenarios like embedded Linux development where understanding interactions between individual components is crucial. It supports both CMake and Meson build systems with automatic build directory detection and switching.
  11. Advanced indexing monitoring tracks both clangd's index state and logs to ensure complete symbol coverage, while intelligent filtering distinguishes between project code and external dependencies.
  12. ## Features
  13. The server provides three core analysis tools for C++ development. The `get_project_details` tool performs dynamic CMake and Meson build environment discovery and enables configuration switching. For symbol exploration, `search_symbols` offers C++ symbol search with project boundary detection and intelligent filtering. When deeper analysis is needed, `analyze_symbol_context` provides symbol analysis with inheritance and call hierarchy support.
  14. The implementation works with both CMake and Meson projects, handling projects with multiple libraries and executables simultaneously. Advanced indexing monitors clangd's index state and logs to ensure complete symbol coverage, while intelligent filtering distinguishes between project code and external dependencies. The server automatically discovers and switches between build configurations, and includes a Python CLI tool for quick symbol exploration.
  15. ## Component Discovery
  16. The MCP server automatically looks for components in the current working directory, scanning 2 levels below by default. This scan depth can be changed using tool options. When an AI agent requests analysis using a build directory outside the project, the MCP server will use that hint path and create a component from it, allowing flexible project analysis beyond the default scanning scope.
  17. ## Dependencies
  18. The server requires clangd 11 or later for C++ semantic analysis (clangd 20+ recommended), and Rust 2024 edition for building. Your project must use CMake or Meson to generate compilation databases (`compile_commands.json`).
  19. You can optionally set the `CLANGD_PATH` environment variable to specify a custom clangd binary location.
  20. ## Installation
  21. ### Install from Crates.io (Recommended)
  22. ```bash
  23. # Install directly from the registry
  24. cargo install mcp-cpp-server
  25. # The binary will be available in your cargo bin directory
  26. # (usually ~/.cargo/bin/mcp-cpp-server)
  27. ```
  28. ### Install from Source
  29. ```bash
  30. # Clone the repository
  31. git clone https://github.com/mpsm/mcp-cpp.git
  32. cd mcp-cpp
  33. # Install from source
  34. cargo install --path .
  35. # The binary will be available in your cargo bin directory
  36. # (usually ~/.cargo/bin/mcp-cpp-server)
  37. ```
  38. ### Docker Installation
  39. ```bash
  40. # Build the Docker image
  41. docker build -t mcp-cpp-server .
  42. # Run with your C++ project mounted
  43. docker run -i --rm -v /path/to/your/cpp-project:/workspace mcp-cpp-server
  44. ```
  45. The Docker image includes:
  46. - mcp-cpp-server binary
  47. - clangd-20 for C++ semantic analysis
  48. - Minimal Ubuntu-based runtime
  49. ## Usage
  50. ### Claude CLI Integration (Tested)
  51. For Claude CLI, create or update your MCP configuration file (`~/.config/claude-cli/mcp_servers.json`):
  52. ```json
  53. {
  54. "mcpServers": {
  55. "cpp-tools": {
  56. "command": "mcp-cpp-server",
  57. "env": {
  58. "CLANGD_PATH": "/usr/bin/clangd-20"
  59. }
  60. }
  61. }
  62. }
  63. ```
  64. ### Amazon Q Developer CLI Integration (Tested)
  65. For Amazon Q Developer CLI, add to your MCP configuration:
  66. ```json
  67. {
  68. "mcpServers": {
  69. "cpp-tools": {
  70. "command": "mcp-cpp-server",
  71. "env": {
  72. "CLANGD_PATH": "/usr/bin/clangd-20"
  73. }
  74. }
  75. }
  76. }
  77. ```
  78. ### Claude Desktop Integration
  79. Add to your Claude Desktop configuration file (`~/.claude_desktop_config.json`):
  80. ```json
  81. {
  82. "mcpServers": {
  83. "cpp-tools": {
  84. "command": "mcp-cpp-server",
  85. "env": {
  86. "CLANGD_PATH": "/usr/bin/clangd-20"
  87. }
  88. }
  89. }
  90. }
  91. ```
  92. ### Claude Code Integration (VS Code Extension)
  93. Claude Code uses a different configuration file location and requires explicit permissions. Add to your Claude Code configuration file (`~/.claude.json`):
  94. ```json
  95. {
  96. "mcpServers": {
  97. "cpp": {
  98. "type": "stdio",
  99. "command": "~/.cargo/bin/mcp-cpp-server",
  100. "args": [],
  101. "env": {
  102. "CLANGD_PATH": "/opt/homebrew/opt/llvm/bin/clangd"
  103. }
  104. }
  105. },
  106. "permissions": {
  107. "allow": [
  108. "mcp__cpp__search_symbols",
  109. "mcp__cpp__analyze_symbol_context",
  110. "mcp__cpp__get_project_details"
  111. ]
  112. }
  113. }
  114. ```
  115. **Notes:**
  116. - Claude Code reads `~/.claude.json`, not `~/.claude/mcp_servers.json`
  117. - The `permissions` section is required to enable the MCP tools
  118. - Adjust the `command` path to match your cargo installation (use `which mcp-cpp-server` to find it)
  119. - Adjust `CLANGD_PATH` to your clangd installation (use `which clangd` to find it, or omit if clangd is in your PATH)
  120. - Tools are prefixed with `mcp__cpp__` in Claude Code (e.g., `mcp__cpp__search_symbols`)
  121. ### Docker Usage with MCP Clients
  122. **Claude Desktop/CLI:**
  123. ```json
  124. {
  125. "mcpServers": {
  126. "cpp-tools": {
  127. "command": "docker",
  128. "args": [
  129. "run", "-i", "--rm",
  130. "-v", "/path/to/cpp-project:/workspace",
  131. "mcp-cpp-server",
  132. "--root", "/workspace"
  133. ]
  134. }
  135. }
  136. }
  137. ```
  138. **Note:** Arguments after the image name are passed to mcp-cpp-server. Use `-e RUST_LOG=debug` for verbose logging.
  139. ## Platform Support
  140. Tested on:
  141. - **Windows with WSL2 Ubuntu**
  142. - **Ubuntu (native)**
  143. - **macOS**
  144. ## Configuration
  145. ### CLI Options
  146. The server supports the following command-line options:
  147. ```bash
  148. mcp-cpp-server --help
  149. # Options:
  150. --root <DIR> Project root directory to scan for build configurations (defaults to current directory)
  151. --clangd-path <PATH> Path to clangd executable (overrides CLANGD_PATH env var)
  152. --log-level <LEVEL> Log level (overrides RUST_LOG env var)
  153. --log-file <FILE> Log file path (overrides MCP_LOG_FILE env var)
  154. ```
  155. ### Environment Variables
  156. - **`CLANGD_PATH`**: Path to clangd executable (default: "clangd")
  157. - **`RUST_LOG`**: Log level - trace, debug, info, warn, error (default: "info")
  158. - **`MCP_LOG_FILE`**: Path to log file (default: logs to stderr only)
  159. - **`MCP_LOG_UNIQUE`**: Set to "true" to append process ID to log filename
  160. ### Python CLI for Debugging
  161. The Python CLI helps you understand what your AI agent sees from the MCP server, making it useful for debugging interactions. Note that this tool is not included in the distributed package and must be used directly from the repository:
  162. ```bash
  163. # Clone the repository if you haven't already
  164. git clone https://github.com/mpsm/mcp-cpp.git
  165. cd mcp-cpp
  166. # Install CLI dependencies
  167. pip install -r tools/requirements.txt
  168. # Search for symbols (see what the agent would see)
  169. python3 tools/mcp-cli.py search-symbols "MyClass"
  170. # Get complete API overview of a header file
  171. python3 tools/mcp-cli.py search-symbols "" --files include/api.h
  172. # Analyze a symbol with examples
  173. python3 tools/mcp-cli.py analyze-symbol "MyClass::process"
  174. # Get project overview
  175. python3 tools/mcp-cli.py get-project-details
  176. ```
  177. ### Basic Workflow
  178. 1. **Get Project Details**
  179. ```json
  180. { "name": "get_project_details" }
  181. ```
  182. With custom scan parameters:
  183. ```json
  184. {
  185. "name": "get_project_details",
  186. "arguments": {
  187. "path": "/path/to/project",
  188. "depth": 5
  189. }
  190. }
  191. ```
  192. 2. **Search C++ Symbols**
  193. ```json
  194. {
  195. "name": "search_symbols",
  196. "arguments": { "query": "std::vector", "include_external": true }
  197. }
  198. ```
  199. File-specific search with custom build directory:
  200. ```json
  201. {
  202. "name": "search_symbols",
  203. "arguments": {
  204. "query": "MyClass",
  205. "files": ["include/MyClass.hpp"],
  206. "build_directory": "build-debug",
  207. "wait_timeout": 30
  208. }
  209. }
  210. ```
  211. 3. **Analyze Symbol Context**
  212. ```json
  213. {
  214. "name": "analyze_symbol_context",
  215. "arguments": {
  216. "symbol": "MyClass::process",
  217. "max_examples": 5
  218. }
  219. }
  220. ```
  221. With location hint for disambiguation:
  222. ```json
  223. {
  224. "name": "analyze_symbol_context",
  225. "arguments": {
  226. "symbol": "factorial",
  227. "build_directory": "/path/to/build",
  228. "location_hint": "/path/to/file.cpp:42:15",
  229. "wait_timeout": 0
  230. }
  231. }
  232. ```
  233. ## Use Cases
  234. The server excels at code exploration and navigation, helping you find functions, classes, and variables across large codebases. It can analyze relationships between code components and navigate system libraries and third-party dependencies to understand how different parts of your project interact.
  235. For code analysis and review, the server provides detailed symbol context including usage patterns, inheritance relationships, and call hierarchies. This helps you explore class hierarchies and call patterns, making it easier to understand unfamiliar code or prepare for refactoring by identifying all usages and dependencies.
  236. The server also assists with development workflows by enabling switching between Debug, Release, and custom build configurations. It provides clear separation between project symbols and external library symbols, making navigation through large C++ codebases more efficient. The cross-reference generation helps you find all references, implementations, and related symbols quickly.
  237. ## Tool Reference
  238. ### C++ Analysis Tools
  239. #### `get_project_details`
  240. **Purpose**: Multi-provider build system analysis and project workspace discovery
  241. **Options**:
  242. - `path` (optional): Project root path to scan. If different from server default, triggers fresh scan
  243. - `depth` (optional): Scan depth for component discovery (0-10 levels, default: 2). Controls how many directory levels below the current working directory to search for CMake/Meson components
  244. **Output**: Complete project analysis including build configurations, components, compilation database status, and multi-provider discovery (CMake, Meson, etc.)
  245. **Component Discovery**: By default, scans 2 levels below the current working directory for components. When AI agents specify build directories outside this scope, the server creates components from those hint paths automatically.
  246. #### `search_symbols`
  247. **Purpose**: Find C++ symbols across your codebase or get complete API overviews
  248. **Key Capabilities**:
  249. - **Symbol Discovery**: Find functions, classes, variables by name or pattern
  250. - **Complete File Overview**: Use empty query (`""`) with file parameter to list all symbols in any file
  251. - **API Exploration**: Perfect for understanding unfamiliar headers or source files
  252. - **Smart Filtering**: Filter by symbol types (Class, Function, Method, etc.) and exclude external libraries
  253. **Common Use Cases**:
  254. ```bash
  255. # Find all vector-related symbols
  256. search_symbols {"query": "vector"}
  257. # Get complete overview of a header file
  258. search_symbols {"query": "", "files": ["include/api.h"]}
  259. # Find only classes and structs
  260. search_symbols {"query": "Process", "kinds": ["Class", "Struct"]}
  261. ```
  262. #### `analyze_symbol_context`
  263. **Purpose**: Deep dive analysis of any C++ symbol with comprehensive context
  264. **What You Get**:
  265. - **Symbol Definition**: Complete type information, location, documentation
  266. - **Usage Examples**: Real code showing how the symbol is used
  267. - **Class Members**: All methods, fields, constructors (for classes)
  268. - **Inheritance Tree**: Base classes and derived classes (for classes)
  269. - **Call Relationships**: What calls this function and what it calls (for functions)
  270. **Perfect For**:
  271. - Understanding unfamiliar code
  272. - Finding all usages before refactoring
  273. - Exploring class hierarchies and relationships
  274. - Learning how to use a function or class
  275. ```bash
  276. # Analyze a class and its members
  277. analyze_symbol_context {"symbol": "MyClass"}
  278. # Deep dive into a specific method
  279. analyze_symbol_context {"symbol": "MyClass::process", "max_examples": 3}
  280. ```
  281. ## Limitations
  282. - Requires CMake or Meson projects that generate `compile_commands.json`
  283. - First-time indexing can take time on large projects (configurable timeout, default 20s)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.