mcpstat is a Python-based analytics and usage-tracking tool designed to work with MCP servers. It provides an audit trail of tool usage, tracks how often tools are invoked, and offers built-in capabilities such as get_tool_usage_stats and get_tool_catalog, along with token and latency tracking. Integrating mcpstat into your MCP workflow lets you monitor tool usage patterns, categorize tools with a tag system, and optionally log all actions to a file for auditing. The package is Reactivated by decorating your tool handlers to automatically collect metrics, so you can keep your business logic clean while gaining visibility into performance and usage.

To use it, install mcpstat and run your MCP server with the provided Python entry point. The library exposes a Server from the MCP ecosystem and a MCPStat tracker, which you attach to your tool handlers via decorators. After setup, you can query usage statistics, catalog information, and latency data to identify slow tools or high-usage patterns. This enables cost analysis, optimization, and better capacity planning for your MCP-based services.

Prerequisites:

• Python 3.10 or newer
• pip (comes with Python)

Installation steps:

1. Install the core package pip install mcpstat

2. (Optional) Install with MCP extra for integration helpers pip install "mcpstat[mcp]"

3. Verify installation python -m pip show mcpstat

4. Run a sample server (adjust as needed for your environment)

   Example using the recommended entry point from the README example

   pip install -e ".".*[mcp] # if you are developing locally python -m mcp.server # or your actual server startup command

5. If needed, install development/testing tools pip install "mcpstat[dev]" && pytest tests/

Notes and tips:

• mcpstat stores usage data in SQLite by default (persistent across restarts); configure alternative storage if required via environment variables or config files.
• The built-in tools like get_tool_usage_stats and get_tool_catalog help you explore which tools are most used and how they are categorized with tags.
• Enable token tracking and latency measurements to understand cost implications and performance characteristics of tools.
• You can enable file-based audit logging for a timestamped trail of actions.
• If you encounter environment-specific issues, ensure your Python environment matches the supported version (Python 3.10+), and verify that the MCP base library your server uses is compatible with mcpstat.
• Review the official documentation linked in the README for configuration options and advanced usage patterns.