mcpstat

Usage tracking and analytics for MCP servers. Pure Python, zero required dependencies.

Track which tools get called, how often, and keep an audit trail - all in 3 lines of code.

Installation

pip install mcpstat

With MCP SDK:

pip install "mcpstat[mcp]"

Quick Start

from mcp.server import Server
from mcpstat import MCPStat

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

@app.call_tool()
@stat.track  # ← One decorator does everything!
async def handle_tool(name: str, arguments: dict):
    # Your logic here - latency tracked automatically
    return await my_logic(arguments)

Then ask your AI assistant: "Give me MCP usage stats"

Features

• SQLite-backed - Stats persist across restarts
• Built-in MCP tools - get_tool_usage_stats, get_tool_catalog
• Tag system - Categorize and filter tools
• Token tracking - Estimate or record actual token usage
• Latency tracking - Measure execution duration, identify slow tools
• File logging - Optional timestamped audit trail
• Async-first - Thread-safe via asyncio.Lock

Documentation

Full Documentation - Quick start, API reference, examples

• Quick Start - Get running in 5 minutes
• Configuration - Customize paths, logging, presets
• API Reference - Complete method reference
• Token Tracking - Cost analysis features
• Latency Tracking - Performance monitoring

Examples

# Clone and run example server
git clone https://github.com/tekkidev/mcpstat.git
cd mcpstat
pip install -e ".[mcp]"
python examples/example_server.py

See examples/ for minimal and full integration patterns.

Contributing

See CONTRIBUTING.md. Run tests with:

pip install "mcpstat[dev]"
pytest tests/

License

MIT - see LICENSE for details.

---

MCP is a trademark of its respective owners. This project is not affiliated with or endorsed by any trademark holders.