Debug Log Analyzer

npm version CI License Node.js TypeScript

A Model Context Protocol (MCP) server that gives AI assistants tools to analyze Salesforce Apex debug logs — surfacing performance bottlenecks, slow methods, and governor limit usage.

Give your AI assistant — Claude, Copilot, or any MCP-compatible client — the ability to parse Apex debug logs and surface the performance insights that matter. Instead of scrolling through thousands of log lines, ask your assistant to find what's slow and why.

Powered by the same powerful log parser as the Apex Log Analyzer VS Code extension used by thousands of Salesforce developers.

Quick Start | What You Can Do | Token Cost | Tools Reference | Configuration | How It Works | Documentation | Contributing | Contributors | License

Quick Start

Requirements: Node.js 22 or later.

_{The execute_anonymous tool additionally needs an org authenticated with the Salesforce CLI.}

Add to your MCP client configuration (claude_desktop_config.json, VS Code mcp.json, etc.):

{
  "mcpServers": {
    "apex-log-mcp": {
      "command": "npx",
      "args": ["-y", "@certinia/apex-log-mcp"]
    }
  }
}

That's it. Open a conversation and ask your AI assistant to analyze an Apex debug log.

What You Can Do

Ask your AI assistant to work with Apex debug logs using natural language:

• "Give me a summary of this debug log"
• "Show me the 5 slowest methods in the default namespace"
• "Are we approaching any governor limits in this transaction?"
• "Run this Apex against my scratch org and analyze the performance"

Token Cost

Enabling the tools

Every request carries all four tool definitions, whether or not a tool is called. That is the standing cost of having the server connected, and each figure is the whole definition as the client receives it — name, title, description, input schema and annotations together.

Tool	Tokens	1.x	Change
execute_anonymous	~428	~844	-49%
analyze_apex_log_performance	~238	~247	-4%
find_performance_bottlenecks	~234	~267	-12%
get_apex_log_summary	~153	~171	-11%
Total	~1,053 (0.5% of a 200K context)	~1,529	-31%

Calling a tool

The input side is the same for every analysis tool — a tool name and a log file path, about 15 tokens — so what a call costs is what it returns. Each row is one tool answering one of the logs in tests/eval/fixtures/, beside what 1.x returned for the same log — the same facts, in a cheaper shape.

Tool	Log	Response	1.x	Change
get_apex_log_summary	governor-heavy.log	~220	~293	-25%
get_apex_log_summary	minimal.log	~174	~249	-30%
analyze_apex_log_performance	governor-heavy.log	~278	~408	-32%
analyze_apex_log_performance	minimal.log	~121	~190	-36%
find_performance_bottlenecks	governor-heavy.log	~79	~84	-6%
find_performance_bottlenecks	minimal.log	~30	~30	0%

Tools Reference

All tools return TOON-encoded data, kept deliberately lean to save tokens — without dropping anything you might need to ask about. See Token Cost for what that is worth in practice.

• Every governor limit, debug category and method column is returned, including the ones at zero. "How many DML statements did this consume?" is answerable from the response, and 0 means none rather than not measured.
• The leanness comes from shape. Data that used to be nested objects is returned as flat tables, which TOON encodes as one header plus one line per row.
• Nothing is reported twice. No prose summary restates the numbers in the table alongside it, and a governor limit detailed in its own section is not repeated in the generic warnings.
• Durations are rounded to 3 decimal places (ms) and percentages to 1.
• Only lists of things that happened are omitted when empty — log issues, recommendations. Nothing to report means the key is absent.

analyze_apex_log_performance

Rank methods in an Apex debug log by self-execution time. Returns method names, durations (in ms), SOQL/DML counts, and optimization recommendations. Best for finding which specific methods to optimize.

Parameter	Type	Required	Description
logFilePath	string	Yes	Absolute path to the Apex debug log file (.log)
topMethods	number	No	Number of slowest methods to return (default: 10)
minDuration	number	No	Minimum duration in milliseconds to include a method (default: 0)
namespace	string	No	Filter methods by namespace

get_apex_log_summary

Get a high-level summary of an Apex debug log including total execution time (in ms), method count, SOQL/DML totals, governor limits, debug levels and active namespaces. Best for a quick overview before deeper analysis.

All thirteen governor limits are listed as {name, used, limit} rows, at zero included, so you can ask what a transaction consumed and get an answer either way. debugLevels names every log category and its level, which is what tells you whether a missing detail was absent from the run or simply never logged.

Parameter	Type	Required	Description
logFilePath	string	Yes	Absolute path to the Apex debug log file (.log)

find_performance_bottlenecks

Check whether an Apex log transaction is approaching governor limits (flags usage above 80%). Analyzes CPU time, SOQL/DML limits, query rows, and method execution patterns by namespace. Best for checking if a transaction is at risk of hitting governor limits.

Parameter	Type	Required	Description
logFilePath	string	Yes	Absolute path to the Apex debug log file (.log)
analysisType	string	No	Type of analysis (default: all). See values below.

analysisType values:

Value	Description
cpu	Checks CPU time governor limit
database	Checks SOQL query, DML statement, and query row limits
methods	Groups methods by namespace with duration totals
all	Runs all three analysis types (default)

execute_anonymous

Executes anonymous Apex code against any authenticated Salesforce org. Saves the resulting debug log to a local file and returns a summary with the file path. Use the file path with get_apex_log_summary, analyze_apex_log_performance, or find_performance_bottlenecks for deeper analysis.

Parameter	Type	Required	Description
apex	string	Yes	The anonymous Apex to be executed
targetOrg	string	No	Alias or username of the target Salesforce org. Uses the project default if not specified.
outputDir	string	No	Directory to save the debug log file. Defaults to .apex-log-mcp/ in the project root.
debugLevel	string | object	No	Trace-flag log levels — see the options below. Omit to keep the current config.

debugLevel options — omit to keep the current config, or pass one of:

• "default" — reset every category to its default.

• a log level (e.g. "FINEST") — set every category to that level.

• an object — override specific categories only; the rest keep their defaults:

  { "database": "FINEST", "apexCode": "FINE" }
  

Valid levels: NONE, ERROR, WARN, INFO, DEBUG, FINE, FINER, FINEST.

📋 Default debug levels — used when debugLevel is omitted (click to expand)

Category	Default Level
apexCode	FINE
apexProfiling	FINE
callout	DEBUG
database	FINEST
nba	INFO
system	DEBUG
validation	DEBUG
visualforce	FINE
wave	INFO
workflow	FINE

Example prompts:

• "Execute this Apex and show me the log: System.debug('Hello');"
• "Run a query for all Accounts and analyze the performance"
• "Execute this Apex with all debug levels set to FINEST"
• "Run this Apex against my QA org with database logging set to FINEST"

Note: Uses the project's default org unless targetOrg is specified. Sandbox, scratch, Developer Edition and trial orgs run without prompting; production orgs are gated — see Production safety. The debug log is saved to a local file (default: .apex-log-mcp/) and the response includes the file path, org username (and alias, if set), org type, and execution summary. Add .apex-log-mcp/ to your .gitignore to avoid committing debug logs.

Configuration

The Quick Start configuration is all you need — all four tools are available by default. The sections below cover the production safety policy and how to change it.

Production safety

execute_anonymous runs arbitrary Apex, so before running anything the server identifies what kind of org it is pointed at. It asks the org once per session:

Org type	Identified by	Behaviour
sandbox	IsSandbox, no trial expiry	Runs
scratch	IsSandbox with a trial expiry	Runs
trial	Not a sandbox, has a trial expiry	Runs
developer	Developer Edition	Runs
production	Anything else	Confirmation required
unknown	The org could not be queried	Confirmation required

For a production org, the server:

1. Runs it anyway if the server was started with --allow-production-orgs.
2. Otherwise asks you to confirm, if your MCP client supports elicitation. The prompt names the org and shows the Apex.
3. Otherwise refuses, and the error explains both ways to proceed.

An org that cannot be identified is treated as production, so a network or permissions problem can never silently downgrade a production org.

Server flags

Flag	Description
--allow-production-orgs	Treat production orgs like any other — no confirmation prompt, no refusal. Only set this if production targets are intentional.
--no-apex-execution	Disable Apex execution entirely. The tool stays visible so agents know it exists, but every call is refused. The three log analysis tools are unaffected.

For an analysis-only deployment:

{
  "mcpServers": {
    "apex-log-mcp": {
      "command": "npx",
      "args": ["-y", "@certinia/apex-log-mcp", "--no-apex-execution"]
    }
  }
}

Migrating from 1.x

--allowed-orgs was removed in 2.0. It is still accepted so existing configurations keep starting, but it is ignored and logs a deprecation warning — you can delete it.

1.x	2.0
No flag (tool hidden)	No flag — the tool is visible and works against non-production orgs
--allowed-orgs ALLOW_ALL_ORGS	No flag. Add --allow-production-orgs only if you target production
--allowed-orgs <org>,<org>	No flag. Org-by-org allowlisting is replaced by the org type policy

Note that ALLOW_ALL_ORGS no longer implies consent to run against production.

How It Works

This server implements the Model Context Protocol (MCP) to expose Apex log analysis as tools that any MCP-compatible AI client can call.

• Runs as a local process — your AI client spawns the server and communicates locally. No network requests, no API keys.
• Uses the same parser as the Apex Log Analyzer VS Code extension — battle-tested parsing of the Apex debug log format.
• Returns structured data — all durations in milliseconds, governor limits as used/limit pairs, methods with SOQL/DML counts — so your AI assistant can reason about the results.
• Keeps responses lean — TOON encoding, no duplicated figures, and zero/empty fields omitted, so more of the context window is left for reasoning.

Documentation

• User Guide & Docs
• MCP Specification

Related Projects

• Apex Log Analyzer VS Code Extension — Full-featured Apex log analyzer for VS Code

Contributing

We welcome contributions! Please see our Contributing Guide for details.

• Developing — Set up your development environment
• Code of Conduct — Community guidelines

Contributors

Thanks to our amazing contributors!

License

Copyright © Certinia Inc. All rights reserved.