mcpstat

السجل الرسمي البيانات وقواعدها

mcpstat documentation and demo server with local usage statistics, a tool catalog, and conversions.

ماذا يمكنك أن تفعل مع mcpstat؟

  • 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

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

PYPI package mcpstat
Claude Code
claude mcp add mcpstat -e 'OTEL_SDK_DISABLED=<OTEL_SDK_DISABLED>' -e 'OTEL_PROPAGATORS=<OTEL_PROPAGATORS>' -- uvx mcpstat==0.3.0
إعداد JSON (Claude Desktop وCursor وVS Code)
{
    "mcpServers": {
        "mcpstat": {
            "command": "uvx",
            "args": [
                "mcpstat==0.3.0"
            ],
            "env": {
                "OTEL_SDK_DISABLED": "<OTEL_SDK_DISABLED>",
                "OTEL_PROPAGATORS": "<OTEL_PROPAGATORS>"
            }
        }
    }
}

متغيرات البيئة

  • OTEL_SDK_DISABLED Disable OpenTelemetry SDK signals for this server process.
  • OTEL_PROPAGATORS Disable OpenTelemetry context and baggage propagation.

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. mcpstat
  2. Installation
  3. Quick Start
  4. Choose Your Integration
  5. Features
  6. Documentation
  7. Examples
  8. Contributing
  9. License

mcpstat

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 caseInstallationWhat it tracks
Add tracking to an existing Python serverpip install mcpstatThe handlers you instrument with the SDK-independent library; keep your server's MCP SDK installed separately.
Run the bundled documentation and demonstration serverpip 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.

الأسئلة الشائعة

ما هو mcpstat؟

mcpstat documentation and demo server with local usage statistics, a tool catalog, and conversions.

كيف أثبّت mcpstat؟

يعمل على جهازك. في Claude Code: claude mcp add mcpstat -e 'OTEL_SDK_DISABLED=<OTEL_SDK_DISABLED>' -e 'OTEL_PROPAGATORS=<OTEL_PROPAGATORS>' -- uvx mcpstat==0.3.0. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج mcpstat إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل mcpstat مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون mcpstat؟

ينشره tekkidev. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.