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

frommcp.serverimportServerfrommcpstatimportMCPStatapp=Server("my-server")
stat=MCPStat("my-server")
@app.call_tool()@stat.track# ← One decorator does everything!asyncdefhandle_tool(name: str, arguments: dict):
# Your logic here - latency tracked automaticallyreturnawaitmy_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.