Skip to content

mcpstat

PyPI - Version GitHub License PyPI - Python Version

mcpstat adds usage tracking and analytics to your MCP (Model Context Protocol) servers. Pure Python stdlib, no required dependencies.

Track which tools get called, how often, and keep an audit trail - all in about three lines of code. Then ask your AI assistant: "Give me MCP usage stats."

Why mcpstat?

MCP is becoming the standard integration layer between AI assistants and external tools. Adding observability to this layer provides concrete benefits:

Benefit Description
Identify active vs. inactive tools Understand which tools deliver value and which can be removed or improved.
Optimize context usage Track whether resources provide useful context or consume tokens without benefit.
Detect usage patterns Spot agent loops, repeated calls, or unexpected tool combinations.
Measure MCP adoption Quantify how often your LLM actually uses MCP integrations.

Without tracking, agents may pull irrelevant resources into context - leading to token waste or lower-quality responses. mcpstat provides the visibility to identify and address these issues.

Features

  • SQLite-backed tracking - Stats persist across restarts
  • Optional file logging - Timestamped audit trail for debugging
  • Built-in tools & prompts - Expose stats directly to LLM clients
  • Metadata enrichment - Tag and describe tools for discoverability
  • Token tracking - Estimate or record actual token usage
  • Async-first - Thread-safe via asyncio.Lock

Quick Start

Installation

pip install mcpstat

For MCP SDK integration:

pip install "mcpstat[mcp]"

Minimal Integration

from mcp.server import Server
from mcpstat import MCPStat

app = Server("my-server")
stat = MCPStat("my-server")  # Initialize

@app.call_tool()
async def handle_tool(name: str, arguments: dict):
    await stat.record(name, "tool")  # Track as FIRST line
    # ... your tool logic

One line - await stat.record(name, "tool") - and you're tracking.

Built-in Tools

mcpstat exposes two tools that AI assistants can call directly:

Tool Purpose Key Parameters
get_tool_usage_stats Call counts & timestamps type_filter, limit, include_zero_usage
get_tool_catalog Browse & search tools tags, query, include_usage, limit

Natural Language Queries

Users can ask AI assistants:

  • "Give me MCP usage stats"
  • "Which tools are used most often?"
  • "List tools tagged with 'temperature'"

The AI invokes get_tool_usage_stats or get_tool_catalog as needed.

Documentation

  • Getting Started

    Install mcpstat and add tracking to your first MCP server in minutes.

    Quick Start

  • Configuration

    Configure paths, logging, metadata presets, and environment variables.

    Configuration

  • Core API

    Complete reference for MCPStat, built-in tools, and handlers.

    API Reference

  • Token Tracking

    Track response sizes and estimate token usage for cost analysis.

    Token Tracking

License

MIT - see LICENSE