mcpstat 0.2.2

Usage tracking, analytics, and file logging for MCP (Model Context Protocol) servers

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.