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.

Metadata

Release files for mcpstat 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcpstat 0.2.2
File	Size	Uploaded
mcpstat-0.2.2.tar.gz	45.5 kB	Feb 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mcpstat 0.2.2
File	Interpreter	ABI	Platform	Reset
mcpstat-0.2.2-py3-none-any.whl 23.0 kB Feb 16, 2026	Python 3	none	any	Details

Total release size: 68.5 kB

Release files / mcpstat-0.2.2.tar.gz

Download URL	mcpstat-0.2.2.tar.gz
Size	45.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`8346e4c8a35359a8000366521e0a673e2b1ffdbfeed18e406e0d067185dc292b`
BLAKE2b-256 checksum How to use checksums	`eb0dbed573866b34c94b68acb579c7adf5dd58b310d74c0837260ebc937b761a`
Upload date	Feb 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.7`

Release files / mcpstat-0.2.2-py3-none-any.whl

Download URL	mcpstat-0.2.2-py3-none-any.whl
Size	23.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0f96ad0ccbe77ea0fea096e11c5c4571058abdc741ccb867d2aa9be20a8be666`
BLAKE2b-256 checksum How to use checksums	`f83b89f05c177136f5d56df44182deb9aa24162ec689ccfa1f6bf014f7241abf`
Upload date	Feb 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.7`