# mcpstat

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6 repo stars
- Author: tekkidev
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/tekkidev/mcpstat
- Updated: 2026-11-16
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/mcpstat

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `OTEL_SDK_DISABLED`, `OTEL_PROPAGATORS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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>

### Codex

**Platform CLI**
```bash
codex mcp add mcpstat --env OTEL_SDK_DISABLED=<OTEL_SDK_DISABLED> --env OTEL_PROPAGATORS=<OTEL_PROPAGATORS> -- 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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e OTEL_SDK_DISABLED=<OTEL_SDK_DISABLED> -e OTEL_PROPAGATORS=<OTEL_PROPAGATORS> 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>

## When to use it
- 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
- 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

## Similar
- [cargo-observability](https://affpapa.org/en/nevibecode/skills/cargo-observability.md) — skill · 7900 installs
- [cx-telemetry-querying](https://affpapa.org/en/nevibecode/skills/cx-telemetry-querying.md) — skill · 6300 installs
- [Flowlines](https://affpapa.org/en/nevibecode/mcp/flowlines.md) — MCP server
- [ai-observability-engineer](https://affpapa.org/en/nevibecode/agents/ai-observability-engineer.md) — subagent · ★ 6505 repo stars
- [troubleshoot-observability](https://affpapa.org/en/nevibecode/skills/troubleshoot-observability.md) — skill · ★ 3232 repo stars
- [dashboard](https://affpapa.org/en/nevibecode/skills/dashboard.md) — skill · ★ 937 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
