Metadata-Version: 2.4
Name: mcpstat
Version: 0.2.1
Summary: Usage tracking, analytics, and file logging for MCP (Model Context Protocol) servers
License: MIT
License-File: LICENSE
Keywords: mcp,model-context-protocol,statistics,analytics,usage-tracking,logging,ai,llm,agent,mcp-server,tool-tracking,observability,token-tracking
Author: Vadim Bakhrenkov
Author-email: hello@vadim.dev
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Provides-Extra: all
Provides-Extra: dev
Provides-Extra: mcp
Requires-Dist: mcp (>=1.0.0) ; extra == "mcp" or extra == "all"
Requires-Dist: mypy (>=1.0) ; extra == "dev" or extra == "all"
Requires-Dist: pytest (>=7.0) ; extra == "dev" or extra == "all"
Requires-Dist: pytest-asyncio (>=0.21) ; extra == "dev" or extra == "all"
Requires-Dist: pytest-cov (>=4.0) ; extra == "dev" or extra == "all"
Requires-Dist: ruff (>=0.1) ; extra == "dev" or extra == "all"
Project-URL: Author, https://vadim.dev
Project-URL: Changelog, https://github.com/tekkidev/mcpstat/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/tekkidev/mcpstat
Project-URL: Issues, https://github.com/tekkidev/mcpstat/issues
Project-URL: Repository, https://github.com/tekkidev/mcpstat
Description-Content-Type: text/markdown

# mcpstat

[![PyPI - Version](https://img.shields.io/pypi/v/mcpstat)](https://pypi.org/project/mcpstat/)
[![GitHub License](https://img.shields.io/github/license/tekkidev/mcpstat?color=yellow)](https://github.com/tekkidev/mcpstat/blob/main/LICENSE)
[![PyPI - Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/mcpstat/)
[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/tekkidev/mcpstat/tests.yaml)](https://github.com/tekkidev/mcpstat/actions/workflows/tests.yaml)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/mcpstat)](https://pypistats.org/packages/mcpstat)
[![Codecov](https://codecov.io/gh/tekkidev/mcpstat/branch/main/graph/badge.svg)](https://codecov.io/gh/tekkidev/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

```bash
pip install mcpstat
```

With MCP SDK:
```bash
pip install "mcpstat[mcp]"
```

## Quick Start

```python
from mcp.server import Server
from mcpstat import MCPStat

app = Server("my-server")
stat = MCPStat("my-server")

@app.call_tool()
async def handle_tool(name: str, arguments: dict):
    await stat.record(name, "tool")  # ← Add as FIRST line
    # ... your tool logic
```

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
- **File logging** - Optional timestamped audit trail
- **Async-first** - Thread-safe via `asyncio.Lock`

## Documentation

**[Full Documentation](https://github.com/tekkidev/mcpstat/tree/main/docs)** - Quick start, API reference, examples

- [Quick Start](https://github.com/tekkidev/mcpstat/blob/main/docs/quickstart.md) - Get running in 5 minutes
- [Configuration](https://github.com/tekkidev/mcpstat/blob/main/docs/configuration.md) - Customize paths, logging, presets
- [API Reference](https://github.com/tekkidev/mcpstat/blob/main/docs/api.md) - Complete method reference
- [Token Tracking](https://github.com/tekkidev/mcpstat/blob/main/docs/token-tracking.md) - Cost analysis features

## Examples

```bash
# 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/](https://github.com/tekkidev/mcpstat/tree/main/examples/) for minimal and full integration patterns.

## Contributing

See [CONTRIBUTING.md](https://github.com/tekkidev/mcpstat/blob/main/CONTRIBUTING.md). Run tests with:

```bash
pip install "mcpstat[dev]"
pytest tests/
```

## License

MIT - see [LICENSE](https://github.com/tekkidev/mcpstat/blob/main/LICENSE) for details.

---

*MCP is a trademark of its respective owners. This project is not affiliated with or endorsed by any trademark holders.*

