Skip to main content

mcpstat

PyPI - Version GitHub License PyPI - Python Version GitHub Actions Workflow Status PyPI - Downloads Checked with mypy Security: bandit Codecov

Python observability and usage analytics for MCP (Model Context Protocol) servers.

Track tool, prompt, and resource calls, successful and failed invocations, and execution latency in local SQLite storage. Add tracking to your existing Python MCP server and expose its statistics as MCP tools that an assistant can query. Optional file logging provides an audit trail.

Installation

pip install mcpstat
pip install "mcpstat[server]"  # Includes the SDK for the example below

Quick Start

from mcp.server import MCPServer
from mcpstat import MCPStat, disable_sdk_tracing

app = MCPServer("my-server")
disable_sdk_tracing(app)
stat = MCPStat("my-server")


@app.tool()
@stat.track(name="echo")
async def echo(message: str) -> str:
    """Return a message, tracking usage and latency automatically."""
    return message


@app.tool()
async def get_tool_usage_stats() -> dict:
    """Return cumulative MCP usage statistics."""
    return await stat.get_stats()


if __name__ == "__main__":
    try:
        app.run()
    finally:
        stat.close()

Connect your assistant to this server, then ask: "Give me MCP usage stats"

For a complete request-to-statistics example, follow the weather server walkthrough. It demonstrates successful calls, an intentional failure, unused tools, and statistics that persist after restarting the server.

Choose Your Integration

Use case Installation What it tracks
Add tracking to an existing Python server pip install mcpstat The handlers you instrument with the SDK-independent library; keep your server's MCP SDK installed separately.
Run the bundled documentation and demonstration server pip install "mcpstat[server]" Its own temperature conversion tools and other registered handlers.

The decorator records usage; register a statistics tool such as get_tool_usage_stats to query that data from Claude Code, VS Code, or another MCP client. The standalone server does not automatically observe other MCP servers.

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 - Database operations run in worker threads with serialized transactions

Install mcpstat for the SDK-independent tracking library. The [server] extra includes the SDK and the runnable mcpstat documentation and demonstration server. The standalone server tracks its own calls; integrate the library into each server you want to monitor.

Documentation

Full Documentation - Quick start, API reference, examples

Examples

# Clone and run example server
git clone https://github.com/tekkidev/mcpstat.git
cd mcpstat
pip install -e ".[dev]"
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.3.0

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.3.0
File Size Uploaded Provenance Actions
mcpstat-0.3.0.tar.gz 69.8 kB With provenance Details for mcpstat-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcpstat 0.3.0
File Interpreter ABI Platform Actions
mcpstat-0.3.0-py3-none-any.whl Python 3 none any Details for mcpstat-0.3.0-py3-none-any.whl

Total release size: 126.1 kB

Release files / mcpstat-0.3.0.tar.gz

Download URL mcpstat-0.3.0.tar.gz
Size 69.8 kB
Tags Source
SHA-256 checksum
How to use checksums
8a9d7b959747e982073251bcc286ca262203019f8b091e1cb05c48e819206606
BLAKE2b-256 checksum
How to use checksums
c8f0ea92dc7a7ecec292bd4c76350acda1591927f0abaa6b81b0ccc0b2e30e1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

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

Download URL mcpstat-0.3.0-py3-none-any.whl
Size 56.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4ba76b0c8c88a46145a68bd0a6371ed3643f6e78030059412cdc20021807c5d0
BLAKE2b-256 checksum
How to use checksums
f91dbe2dfad4ca3ae185b5da73a0716d4b450e46bb52e3499648015cf4147431
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for mcpstat 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcpstat-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page