Apex Log MCP Server

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 apexlog_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.

Related MCP server: Log Reader MCP

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.

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 the same log, beside what 1.x returned for it — the same facts, in a cheaper shape.

What a call costs does not scale with the log. The response is bounded by its shape — a fixed table of governor limits, and a row cap on the ranked operations — and not by the bytes parsed. The log measured below is a 40 KB slice of the Apex Log Analyzer sample log; against the unsliced 19.7 MB original, apexlog_get_summary returns ~374 tokens rather than the ~364 below, and apexlog_list_limit_risks returns the same ~39.

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 operation 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 no figure appears in two places.

• Durations are rounded to 3 decimal places (ms) and percentages to 1.

• Only what did not happen is omitted — the fatal errors that ended a transaction, how a partial log lost content and how much, and the query plans behind the ranked rows. Nothing to report means the key is absent; every other field reports its zero.

apexlog_list_slow_operations

Rank what an Apex debug log spent its time on by self-execution time — code units, methods, queries, searches, DML, flows and workflows in one table, each row with its calls, durations (in ms), database counts and rows, beside the query optimizer's plan for the queries among them. Best for finding what to optimize.

Rows are {debugCategory, type, name, namespace, callCount, durationTotalMs, durationSelfMs, durationSelfMaxMs, selfPercentage, soqlCount, dmlCount, soslCount, rowCount, thrownCount}, beside the transaction's durationTotalMs, the returnedSelfPercentage the returned rows account for between them, and the matchedCount the selection matched before paging cut it. durationSelfMaxMs is the self time of the slowest single call in a grouped row — read against durationSelfMs it tells one bad call from sheer volume — and is absent when each row is one call already.

Both classification columns come straight from the log. debugCategory is the Salesforce debug log category the platform stamped on the event — apexCode, database, system, visualforce, workflow, and so on — which is the category that decided whether the event was written at all, and the same spelling apexlog_execute_anonymous takes as input. type is the log's own event type, which is what the category cannot say: SOQL_EXECUTE_BEGIN, SOSL_EXECUTE_BEGIN and DML_BEGIN all sit under database, and an ENTERING_MANAGED_PKG row — the time a package spent where the log shows nothing, often most of a transaction — sits under apexCode beside the methods it hides.

sortBy: "heapSelfNetBytes" ranks by the heap each row's own code retained instead of by time, adding a heapSelfNetBytes column and a returnedHeapPercentage scalar — the share of the transaction's retained heap the returned rows carry, which the rows cannot imply and no other tool reports. Both are absent from a ranking that did not ask for them. The figure is the signed HEAP_ALLOCATE bytes, so a row that released more than it took reads below zero, and an allocation reaches the log only at APEX_CODE,FINER and above — the apexCode row of capturedAt says whether a zero can be real.

capturedAt gives {debugCategory, level} for each category among the returned rows, so the levels join to the rows on the same key.

queryPlans gives what the query optimizer decided about the queries behind the returned rows — {leadingOperationType, relativeCost, cardinality, sObjectCardinality}, where a relativeCost above 1 means the optimizer will not treat the query as selective. It is absent when the log explained none of them, which the database row of capturedAt explains: an explain line is written at database,FINEST alone. Each plan names its row as operationRow, the 1-based line of operations as returned — except under a namespace, callerNamespace or debugCategory grouping, where the row is not named after the query and the plan carries the query text as name instead.

A page is bounded by size as well as by limit, so you can get fewer rows than you asked for. matchedCount above the rows returned is what says so; advance offset by the rows you got, not by limit.

apexlog_get_summary

Get a high-level summary of an Apex debug log: how long the transaction ran (in ms), where the time went by debug log category, every governor limit it and each namespace consumed, the debug levels it was logged at, whether the log is complete, and what ended the transaction if it failed. Best for a quick overview before deeper analysis.

All thirteen governor limits are listed as {limit, used, max} rows, at zero included, so you can ask what a transaction consumed and get an answer either way. limitsByNamespace adds {namespace, limit, used} rows for each limit a namespace consumed, which is how you see that a managed package spent your CPU time; it names no ceiling, because the parser keeps one ceiling per limit for the whole transaction and it is already in governorLimits.

timeByCategory gives {debugCategory, operationCount, durationSelfMs, selfPercentage} for all eleven debug log categories, at zero included. The category is the one that decided whether an operation was written to the log at all, so a zero can be read against debugLevels, whose rows are {debugCategory, level}: database 0 beside database NONE means the queries were not logged, and beside database FINEST it means none ran. Three categories — dataAccess, wave and validation — can only ever be zero, because no timed event carries them.

truncated says whether the log is complete — every figure in a partial one is a floor, not a total. Where the platform is what cut it, truncatedBy names how (skipped-lines for a hole in the middle, max-size for a tail never written) and skippedBytes how much it dropped; both are absent on a log that merely stops mid-frame, which the platform did not cut and states no byte count for. thrownCount is how many exceptions were thrown, at zero included. fatalErrors gives {message, frames} for each failure that ended a transaction, and is absent when none did; frames holds the innermost three stack frames, with a trailing … where there were more. It is the only field that says a transaction did not finish, which decides what every other figure means — a fatal error need breach no governor limit, so nothing else in the response reveals one.

apexlog_list_limit_risks

List the governor limits an Apex log transaction has nearly consumed — CPU time, heap, SOQL and SOSL queries, DML statements, and the rows each returned or wrote — worst first, with how much of each was used. Best for checking whether a transaction is at risk of failing on a limit.

Rows are {limit, used, max, usedPercentage}. The threshold that produced them is reported alongside, so an empty table reads as "nothing is that far consumed" rather than as a missing answer.

capturedAt gives {debugCategory, level} for the two categories that decide whether a limit figure was written at all: apexProfiling, which gates the cumulative limit blocks every limit but heap is read from, and apexCode, which gates the heap allocations behind heapSize.

apexlog_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 apexlog_get_summary, apexlog_list_slow_operations, or apexlog_list_limit_risks for deeper analysis.

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.

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

apexlog_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:

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

For an analysis-only deployment:

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

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/max rows, operations with SOQL/DML counts — so your AI assistant can reason about the results.

• Keeps responses lean — TOON tables and no duplicated figures, so more of the context window is left for reasoning. The fields stay, including the ones at zero: see Tools Reference.

• Parses a log once, not once per tool — a summary followed by a deeper analysis of the same file reuses the parse, so a large log is read and parsed one time.

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