mcpstat — Claude Code MCP server: what it does, how to install
mcpstat — an MCP server for Claude Code logging tool calls, latency, and errors into local SQLite storage. Exposes gathered metrics to the assistant via built-in inspection tools.
MIT ★ 6 updated 2026-11-16
claude mcp add --env OTEL_SDK_DISABLED=<OTEL_SDK_DISABLED> --env OTEL_PROPAGATORS=<OTEL_PROPAGATORS> --transport stdio mcpstat -- uvx mcpstatWhat mcpstat does
The server records invocations, failures, and execution duration for MCP tools, prompts, and resources. Every record lands in a local SQLite file, so all metrics persist across process restarts. Timestamped file logging is also available for audit trails.
Querying usage is handled by built-in tools like get_tool_usage_stats and get_tool_catalog. The system tracks estimated or recorded tokens, measures execution latency to uncover bottlenecks, and uses tags to group registered tools. Database operations run through dedicated worker threads with serialized transactions.
The standalone server tracks only its own handlers and cannot inspect external MCP instances automatically. Monitoring a custom Python service requires installing the mcpstat package directly and wrapping target handlers with @stat.track. Python 3.10+ is required.
What it helps with
- store MCP tool call history and latency inside SQLite
- identify failing or high-latency tools using persisted logs
- track token usage across different handler executions
- inspect cumulative tool metrics directly through assistant prompts
Example prompts for the agent
- Show MCP usage stats using get_tool_usage_stats
- List available tools and metadata via get_tool_catalog
- Check execution latency and failures for tracked handlers
How to install mcpstat
Platform CLI
claude mcp add --env OTEL_SDK_DISABLED=<OTEL_SDK_DISABLED> --env OTEL_PROPAGATORS=<OTEL_PROPAGATORS> --transport stdio mcpstat -- uvx mcpstatReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcpstat <command>
Platform CLI
codex mcp add mcpstat --env OTEL_SDK_DISABLED=<OTEL_SDK_DISABLED> --env OTEL_PROPAGATORS=<OTEL_PROPAGATORS> -- uvx mcpstatReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcpstat <command>
Config file
{
"mcpServers": {
"mcpstat": {
"command": "uvx",
"args": [
"mcpstat"
],
"env": {
"OTEL_SDK_DISABLED": "<OTEL_SDK_DISABLED>",
"OTEL_PROPAGATORS": "<OTEL_PROPAGATORS>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcpstat <command>
Config file
{
"servers": {
"mcpstat": {
"type": "stdio",
"command": "uvx",
"args": [
"mcpstat"
],
"env": {
"OTEL_SDK_DISABLED": "<OTEL_SDK_DISABLED>",
"OTEL_PROPAGATORS": "<OTEL_PROPAGATORS>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcpstat <command>
Platform CLI
gemini mcp add -e OTEL_SDK_DISABLED=<OTEL_SDK_DISABLED> -e OTEL_PROPAGATORS=<OTEL_PROPAGATORS> mcpstat uvx mcpstatReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcpstat <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcpstat
How to install mcpstat in Claude Code?
Run claude mcp add mcpstat -- uvx mcpstat. If you need custom telemetry environment variables, run claude mcp add --env OTEL_SDK_DISABLED=<OTEL_SDK_DISABLED> --env OTEL_PROPAGATORS=<OTEL_PROPAGATORS> --transport stdio mcpstat -- uvx mcpstat.
What does mcpstat do?
It monitors tool, prompt, and resource calls, storing execution durations, token usage, and failure counts in local SQLite storage.
Does the standalone server track other running MCP servers?
No, the standalone instance only observes its own registered tools. Tracking third-party servers requires importing the mcpstat library and decorating handlers in each Python service.