Metadata-Version: 2.4
Name: aiogram-mcp
Version: 0.2.0
Summary: MCP server middleware for aiogram Telegram bots — expose your bot to AI agents via the Model Context Protocol
Project-URL: Homepage, https://github.com/Py2755/aiogram-mcp
Project-URL: Repository, https://github.com/Py2755/aiogram-mcp
Project-URL: Issues, https://github.com/Py2755/aiogram-mcp/issues
Project-URL: Changelog, https://github.com/Py2755/aiogram-mcp/blob/main/CHANGELOG.md
Author: Py2755
License: MIT
License-File: LICENSE
Keywords: ai,aiogram,anthropic,bot,claude,mcp,model-context-protocol,telegram
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiogram>=3.20.0
Requires-Dist: fastmcp>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# aiogram-mcp

[![CI](https://github.com/Py2755/aiogram-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Py2755/aiogram-mcp/actions/workflows/ci.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/aiogram-mcp.svg)](https://pypi.org/project/aiogram-mcp/)

MCP server middleware for aiogram Telegram bots.

`aiogram-mcp` lets you expose an existing [aiogram](https://github.com/aiogram/aiogram) bot to [MCP](https://modelcontextprotocol.io/) clients such as Claude Desktop without rewriting handlers, routers, or business logic.

## Status

**Beta** — the core API is stable but may change before 1.0.

## Installation

```bash
pip install aiogram-mcp
```

Requirements:

- Python 3.10+
- aiogram 3.20+

## Quickstart

```python
from aiogram import Bot, Dispatcher
from aiogram_mcp import AiogramMCP

bot = Bot(token="YOUR_BOT_TOKEN")
dp = Dispatcher()

# Register your normal handlers here.

mcp = AiogramMCP(bot=bot, dp=dp)
await mcp.run_alongside_bot(transport="stdio")
```

Available transports:

- `stdio` for Claude Desktop and local MCP clients
- `sse` for remote HTTP-based MCP connections

## Built-in Tools

Messaging:

- `send_message`
- `send_photo`
- `forward_message`
- `delete_message`
- `pin_message`

Users:

- `get_bot_info`
- `get_chat_member_info`
- `get_user_profile_photos`

Chats:

- `get_chat_info`
- `get_chat_members_count`
- `ban_user`
- `unban_user`
- `set_chat_title`
- `set_chat_description`

Broadcast:

- `broadcast` when `enable_broadcast=True`

## MCP Resources

Read-only data exposed to AI agents without tool calls:

| URI | Description |
|---|---|
| `telegram://bot/info` | Bot metadata (username, capabilities) |
| `telegram://config` | Server configuration and allowed chat IDs |
| `telegram://chats` | Active chats the bot has seen (requires middleware) |
| `telegram://chats/{chat_id}/history` | Recent message history for a chat |

Resources require `MCPMiddleware` to be attached for chat tracking and message history.

## Safety Controls

```python
mcp = AiogramMCP(
    bot=bot,
    dp=dp,
    name="my-bot",
    allowed_chat_ids=[123456789, -1001234567890],
    enable_broadcast=True,
    max_broadcast_recipients=500,
)
```

Use `MCPMiddleware` to track chats, users, and message history for MCP resources:

```python
from aiogram_mcp import AiogramMCP, MCPMiddleware

tracker = MCPMiddleware(history_size=50)
dp.message.middleware(tracker)

mcp = AiogramMCP(bot=bot, dp=dp, middleware=tracker, enable_broadcast=True)
```

## Development

```bash
pip install -e ".[dev]"
ruff check aiogram_mcp tests examples
mypy aiogram_mcp
pytest -v
```

Project layout:

- `aiogram_mcp/` package source
- `tests/` unit tests
- `examples/` runnable usage examples
- `.github/workflows/ci.yml` GitHub Actions pipeline

## Examples

- [basic_bot.py](examples/basic_bot.py)
- [incident_alert_bot.py](examples/incident_alert_bot.py)

## License

MIT. See [LICENSE](LICENSE).
