Skip to main content
MCP server CX Codex

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

Install into Claude Code · Platform CLI All methods and platforms ↓
claude mcp add --env OTEL_SDK_DISABLED=<OTEL_SDK_DISABLED> --env OTEL_PROPAGATORS=<OTEL_PROPAGATORS> --transport stdio mcpstat -- uvx mcpstat
Open on GitHub

What 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 mcpstat

Replace <…> 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.

Similar MCP servers

All MCP servers for Agent setup: memory, context, orchestration →

Project sponsors

Companies that keep this analytics open