arm-code-mcp
Provides tools to analyze performance, suggest NEON SIMD intrinsics, and audit Python dependency manifests for arm64 compatibility, enabling optimization of Linux workloads on Arm64.
Helps optimize Linux workloads on Arm64 by parsing perf report output and identifying hot symbols for performance tuning.
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., "@arm-code-mcp check arm64 deps in my requirements.txt"
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.
arm-code-mcp
An MCP server that helps AI assistants optimize Linux workloads on Arm64.
It parses perf report output, recommends NEON SIMD intrinsics for hot loops,
and audits Python dependency manifests for arm64 wheel availability —
all offline, all structured, all callable from Claude Code, GitHub Copilot, and Codex.
What's inside
analyze_perf_output— parseperf report --stdiointo a ranked list of hot symbolssuggest_neon_intrinsic— semantic + keyword search over 110 curated NEON intrinsicscheck_arm64_deps— flag packages inrequirements.txt,pyproject.toml, orDockerfilethat lack arm64 wheels or require special handling
Related MCP server: perf-mcp
Prerequisites
Docker
An MCP-compatible AI assistant (Claude Code, GitHub Copilot, Codex)
Quick start
docker pull jeannjohnson/arm-code-mcp:latestAdd to your MCP client config (e.g. ~/.claude/mcp.json):
{
"mcpServers": {
"arm-code-mcp": {
"command": "docker",
"args": ["run", "--rm", "-i", "jeannjohnson/arm-code-mcp:latest"]
}
}
}Restart your client. All three tools are now available.
Tools
analyze_perf_output
Parse raw perf report --stdio output and return the top hot symbols, ranked by overhead.
analyze_perf_output(
perf_report_text: str, # raw stdout of `perf report --stdio`
top_n: int = 10, # max symbols to return
min_overhead_pct: float = 0.5, # ignore symbols below this %
) -> dictExample response:
{
"summary": {
"total_samples": 5432100,
"total_events": null,
"command": "myapp"
},
"hot_symbols": [
{"overhead_pct": 24.17, "samples": 1245, "command": "myapp",
"module": "myapp", "symbol": "process_buffer"},
{"overhead_pct": 12.34, "samples": 636, "command": "myapp",
"module": "libc-2.31.so", "symbol": "__memcpy_avx_unaligned_erms"}
],
"warnings": []
}suggest_neon_intrinsic
Recommend NEON intrinsics for a hot loop using hybrid semantic + exact-name retrieval over a curated knowledge base of 110 intrinsics.
suggest_neon_intrinsic(
operation_description: str, # e.g. "32-bit float multiply-accumulate"
target_arch: str = "armv8-a", # "armv8-a" | "armv8.2-a" | "armv9-a"
top_k: int = 5,
) -> dictExample response:
{
"matches": [
{
"intrinsic": "vmlaq_f32",
"signature": "float32x4_t vmlaq_f32(float32x4_t a, float32x4_t b, float32x4_t c)",
"header": "<arm_neon.h>",
"min_arch": "armv8-a",
"description": "Multiply-accumulate: a + (b * c), lane-wise, 4x f32.",
"score": 0.9142
}
],
"notes": "Filtered to armv8-a. KB contains 110 entries (103 compatible)."
}check_arm64_deps
Scan a dependency manifest and flag packages with known arm64 compatibility issues. Fully offline — no network calls, fast, deterministic.
check_arm64_deps(
file_content: str, # raw text of the manifest
file_type: str = "requirements.txt", # "requirements.txt" | "pyproject.toml" | "Dockerfile"
) -> dictExample response:
{
"checked": ["numpy", "tensorflow", "cupy-cuda12x", "faiss-cpu", "requests"],
"issues": [
{"package": "cupy-cuda12x", "severity": "error",
"message": "GPU-only package with no arm64 wheel. Use cupy with ROCm or a CPU fallback."},
{"package": "tensorflow", "severity": "warning",
"message": "Official TensorFlow PyPI wheels are x86-only before 2.10; use tensorflow-aarch64 or build from source."},
{"package": "faiss-cpu", "severity": "warning",
"message": "No official arm64 wheel on PyPI; build from source or use the conda-forge package."},
{"package": "numpy", "severity": "info",
"message": "arm64 wheels available from PyPI since 1.21.0. Ensure version >= 1.21.0."}
],
"summary": "Checked 5 package(s): 1 error(s), 2 warning(s), 1 info(s)."
}Severity levels:
Level | Meaning |
| No arm64 wheel exists (e.g. GPU-only packages) |
| Wheel exists but requires a workaround or alternative source |
| Wheel available; version constraint or system-lib note applies |
Configuration
All env vars are optional. The server works with no configuration.
Variable | Default | Description |
|
| Log verbosity: |
| bundled JSONL | Override path to |
|
| Embedding cache directory |
Pass env vars to the container:
docker run --rm -i \
-e ARM_CODE_MCP_LOG_LEVEL=DEBUG \
jeannjohnson/arm-code-mcp:latestEvaluation
suggest_neon_intrinsic is evaluated against 15 hand-curated (query, expected intrinsic) pairs
using the real all-MiniLM-L6-v2 embedding model. Current baseline:
Metric | Score |
hit@1 | 0.667 |
hit@3 | 0.933 |
hit@5 | 1.000 |
MRR | 0.817 |
The regression guard exits non-zero if hit@3 drops below 0.70.
Run the eval harness locally:
uv sync
make evalSee eval/README.md for methodology and known limitations.
Development
git clone https://github.com/jean-johnson-zwix/arm-code-mcp
cd arm-code-mcp
uv sync
make test # 78 tests
make lint # ruff check + format
make eval # real model, 15 gold queriesMakefile targets:
Target | Description |
|
|
| Run the full test suite |
| ruff check + ruff format --check |
| Run the NEON retrieval eval harness |
| Build |
| Run the local dev image over stdio |
Multi-arch images (linux/amd64 + linux/arm64) are built and pushed automatically
by .github/workflows/release.yml on v*.*.* tags.
Knowledge base maintenance
The NEON intrinsics knowledge base lives in src/arm_code_mcp/kb/data/neon_intrinsics.jsonl
(110 entries). To add intrinsics or refresh after a model upgrade, see docs/kb-refresh.md.
Roadmap
Tools
parse_flamegraph— extract hot paths from Linux perf flamegraph SVGsuggest_sve2_intrinsic— extend retrieval to SVE2 intrinsics (Neoverse V2, Cortex-X4)
Eval
Multi-query paraphrase expansion for each gold pair
Reranking pass over semantic candidates
Larger gold set (50+ queries) for lower metric variance
Demo
Coming soon.
Contributing
Stars, forks, and issues are welcome. Open a PR or file an issue on GitHub.
Good first issues:
Add more NEON intrinsic entries to
kb/data/neon_intrinsics.jsonlAdd gold eval queries for SVE2 intrinsics
Add
parse_flamegraphtool for Linux perf flamegraph SVG files
License
Apache 2.0 — same as arm/mcp.
Available Tools
4 toolsanalyze_perf_outputA
Parse the text output of perf report --stdio and return the top hot symbols.
Use this tool when a user pastes `perf report --stdio` output and wants to know
which functions are consuming the most CPU cycles on their Arm64 system.
Args:
perf_report_text: Raw stdout of `perf report --stdio` or similar.
top_n: Maximum number of hot symbols to return (default 10).
min_overhead_pct: Filter out symbols below this overhead percentage (default 0.5).
Returns:
{
"summary": {"total_samples": int, "total_events": int | None, "command": str | None},
"hot_symbols": [
{"overhead_pct": 12.34, "samples": 1234, "command": "...",
"module": "...", "symbol": "..."},
...
],
"warnings": [...]
}
Example: analyze_perf_output(perf_report_text=text, top_n=5, min_overhead_pct=1.0)
returns the 5 hottest symbols above 1% overhead.
Inputs: perf_report_text (required), top_n, min_overhead_pct.
check_arm64_depsA
Scan a dependency manifest for known arm64 compatibility issues.
Use this tool when a user wants to know whether their Python dependencies
will install on an Arm64 server (AWS Graviton, Google Axion, Ampere Altra,
Raspberry Pi 5), or when they ask why a package fails on arm64.
Args:
file_content: Raw text of the dependency manifest.
file_type: One of "requirements.txt", "pyproject.toml", or "Dockerfile".
Returns:
{
"checked": ["numpy", "tensorflow", ...],
"issues": [
{"package": "tensorflow", "severity": "warning",
"message": "Official TensorFlow PyPI wheels are x86-only..."}
],
"summary": "Checked 5 package(s): 1 warning(s)."
}
Severity levels: "error" = no arm64 wheel at all (e.g. GPU-only packages);
"warning" = arm64 wheel exists but requires workaround;
"info" = wheel available but version constraint or system lib note applies.
Example: check_arm64_deps(content, "requirements.txt") flags cupy (error),
tensorflow (warning), and reports numpy arm64 wheel availability (info).
Inputs: file_content (required), file_type.
pingA
Health-check — returns "pong: ". Example: ping(message="hello") → "pong: hello".
Inputs: message (required). Returns: result
suggest_neon_intrinsicA
Suggest NEON SIMD intrinsics for an operation description, ranked by semantic similarity.
Use this tool when a user asks which NEON intrinsic to use for a hot loop, wants to
vectorize an operation on Arm64, or mentions intrinsic names like vmlaq_f32.
Args:
operation_description: Natural-language description of the operation
(e.g., "vectorized 32-bit float multiply-accumulate" or "vmlaq_f32").
target_arch: Target Arm architecture — "armv8-a" (default), "armv8.2-a", or "armv9-a".
top_k: Number of suggestions to return (default 5).
Returns:
{
"matches": [
{"intrinsic": "vmlaq_f32", "signature": "...", "header": "<arm_neon.h>",
"min_arch": "armv8-a", "description": "...", "score": 0.83},
...
],
"notes": "Filtered to armv8-a. KB contains N entries (M compatible)."
}
Example: suggest_neon_intrinsic("32-bit float fused multiply-add") returns vfmaq_f32 at rank 1.
Inputs: operation_description (required), top_k, target_arch.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct job: health check, parsing perf output, suggesting NEON intrinsics, and scanning dependency manifests. No two tools overlap or create selection ambiguity.
Three tools follow a clear verb_noun pattern (analyze_perf_output, suggest_neon_intrinsic, check_arm64_deps). The ping health-check tool is a minor deviation, but it's a conventional exception.
Four tools is a well-scoped size for a specialized Arm64 code assistant. Each tool provides standalone value without redundancy.
The tool set covers profiling output analysis, NEON intrinsic lookup, and Arm64 dependency compatibility with no obvious dead ends. Minor gaps exist (e.g., no disassembly or compile-flag assistance), but the core purpose is reasonably served.
Maintenance
Related MCP Connectors
CVE lookups (NVD) and dependency-manifest audits (OSV) for AI agents. No API keys.
CVE lookups (NVD) and dependency-manifest audits (OSV) for AI agents. No API keys.
Checks AI-written code for leaked keys and made-up packages, on your machine. Never uploads code.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to record, analyze, and compare Xcode Instruments traces, detect performance bottlenecks and regressions, and provide optimization recommendations.44MIT
- FlicenseAqualityDmaintenanceEnables LLMs to analyze Linux perf data files using 26 perf analysis commands, including report, script, annotate, and more, through typed tool parameters.26-

Arm MCP Serverofficial
AlicenseNot gradedqualityAmaintenanceProvides AI assistants with tools for Arm architecture development, migration, and optimization, including knowledge base search, code migration analysis, container inspection, assembly performance analysis, and workload performance testing.95Apache 2.0- AlicenseAqualityDmaintenanceAnalyzes, plans, and benchmarks LLM workload migration from x86 to Arm64, generating measurable speedups using free GitHub Arm runners.4MIT