agent-telegram-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. agent_telegram_mcp-0.1.0/.env.example +4 -0
  2. agent_telegram_mcp-0.1.0/.gitignore +29 -0
  3. agent_telegram_mcp-0.1.0/PKG-INFO +88 -0
  4. agent_telegram_mcp-0.1.0/README.md +73 -0
  5. agent_telegram_mcp-0.1.0/pyproject.toml +32 -0
  6. agent_telegram_mcp-0.1.0/requirements.txt +3 -0
  7. agent_telegram_mcp-0.1.0/tele_bot_mcp/__init__.py +0 -0
  8. agent_telegram_mcp-0.1.0/tele_bot_mcp/server.py +757 -0
  9. agent_telegram_mcp-0.1.0/uv.lock +840 -0
agent_telegram_mcp-0.1.0/.env.example ADDED
@@ -0,0 +1,4 @@
1
+ # Copy this file to .env and fill in your Telegram Bot Token
2
+ # Get one from https://t.me/BotFather
3
+
4
+ TELEGRAM_BOT_TOKEN=your_telegram_bot_token
agent_telegram_mcp-0.1.0/.gitignore ADDED
@@ -0,0 +1,29 @@
1
+ # Environments
2
+ .env
3
+ .venv
4
+ env/
5
+ venv/
6
+ ENV/
7
+ env.bak/
8
+ venv.bak/
9
+
10
+ # Byte-compiled / optimized / DLL files
11
+ __pycache__/
12
+ *.py[cod]
13
+ *$py.class
14
+
15
+ # Distribution / packaging
16
+ dist/
17
+ build/
18
+ *.egg-info/
19
+ .eggs/
20
+
21
+ # IDEs
22
+ .idea/
23
+ .vscode/
24
+
25
+ # Ruff / Pytest
26
+ .pytest_cache/
27
+ .ruff_cache/
28
+ .coverage
29
+ htmlcov/
agent_telegram_mcp-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,88 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-telegram-mcp
3
+ Version: 0.1.0
4
+ Summary: Telegram MCP Server — lets AI agents send/receive Telegram messages via a Bot Token
5
+ Project-URL: Repository, https://github.com/tharindumendis/Agent_telegeam_mcp
6
+ Author: Tharindu Mendis
7
+ License: MIT
8
+ Keywords: agent,ai,bot,llm,mcp,stdio,telegram
9
+ Requires-Python: >=3.10
10
+ Requires-Dist: httpx>=0.27.0
11
+ Requires-Dist: mcp[cli]>=1.0.0
12
+ Requires-Dist: pydantic>=2.0.0
13
+ Requires-Dist: python-dotenv>=1.0.0
14
+ Description-Content-Type: text/markdown
15
+
16
+ # agent-telegram-mcp
17
+
18
+ A robust Model Context Protocol (MCP) server that enables AI agents to seamlessly interact with Telegram using a standard Bot Token. It provides a comprehensive suite of tools for bidirectional communication, including sending and receiving text messages, multimedia, documents, and managing chats.
19
+
20
+ ## Installation
21
+
22
+ Install using `pip` or `uv`:
23
+
24
+ ```bash
25
+ pip install agent-telegram-mcp
26
+ ```
27
+ or
28
+ ```bash
29
+ uv tool install agent-telegram-mcp
30
+ ```
31
+
32
+ ## Configuration
33
+
34
+ This MCP server requires a Telegram Bot Token. You can create a new bot and obtain your token by talking to the [BotFather](https://t.me/botfather) on Telegram.
35
+
36
+ To use this server with MCP-compatible clients (like Claude Desktop, Agent_head, etc.), add it to your server configuration and pass the token as an environment variable:
37
+
38
+ ### Example `mcp_config.json`
39
+ ```json
40
+ {
41
+ "mcpServers": {
42
+ "agent-telegram-mcp": {
43
+ "command": "agent-telegram-mcp",
44
+ "env": {
45
+ "TELEGRAM_BOT_TOKEN": "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
46
+ }
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ ## Available Tools
53
+
54
+ The server exposes the following tools to the LLM agent:
55
+
56
+ ### ✉️ Messaging
57
+ - **`telegram_send_message`**: Send text messages (supports Markdown, HTML, silent messages, and replies).
58
+ - **`telegram_forward_message`**: Forward existing messages between chats.
59
+ - **`telegram_delete_message`**: Delete a message from a chat (requires bot admin permissions).
60
+ - **`telegram_pin_message`**: Pin a message in a group/channel.
61
+
62
+ ### 🖼️ Media & Files
63
+ - **`telegram_send_photo`**: Send images via a local file path, public HTTP URL, or Telegram file ID.
64
+ - **`telegram_send_video`**: Send video files.
65
+ - **`telegram_send_audio`**: Send audio tracks (renders as a Telegram music player).
66
+ - **`telegram_send_voice`**: Send voice notes (`.ogg` files).
67
+ - **`telegram_send_document`**: Send arbitrary files (PDFs, ZIPs, code snippets, etc.).
68
+ - **`telegram_send_sticker`**: Send `.webp` stickers.
69
+ - **`telegram_send_location`**: Send a geographic map pin via latitude and longitude.
70
+
71
+ ### 📥 Retrieval & Info
72
+ - **`telegram_get_updates`**: Retrieve recent messages, commands, and callback queries sent to the bot (supports pagination with `offset` and `limit`).
73
+ - **`telegram_get_chat_info`**: Fetch detailed information about a user, group, or channel.
74
+ - **`telegram_get_chat_member_count`**: Check how many users are in a chat.
75
+ - **`telegram_get_file_info`**: Retrieve metadata and the download path for a file hosted on Telegram servers.
76
+ - **`telegram_download_file`**: Download a file to a specific local path or return its contents as a Base64 string.
77
+ - **`telegram_get_bot_info`**: Fetch the current bot's profile information to verify the token connection.
78
+
79
+ ## Development & Testing
80
+
81
+ You can run the server directly via standard I/O (stdio) transport:
82
+
83
+ ```bash
84
+ export TELEGRAM_BOT_TOKEN="your-token"
85
+ # On Windows: set TELEGRAM_BOT_TOKEN=your-token
86
+
87
+ agent-telegram-mcp
88
+ ```
agent_telegram_mcp-0.1.0/README.md ADDED
@@ -0,0 +1,73 @@
1
+ # agent-telegram-mcp
2
+
3
+ A robust Model Context Protocol (MCP) server that enables AI agents to seamlessly interact with Telegram using a standard Bot Token. It provides a comprehensive suite of tools for bidirectional communication, including sending and receiving text messages, multimedia, documents, and managing chats.
4
+
5
+ ## Installation
6
+
7
+ Install using `pip` or `uv`:
8
+
9
+ ```bash
10
+ pip install agent-telegram-mcp
11
+ ```
12
+ or
13
+ ```bash
14
+ uv tool install agent-telegram-mcp
15
+ ```
16
+
17
+ ## Configuration
18
+
19
+ This MCP server requires a Telegram Bot Token. You can create a new bot and obtain your token by talking to the [BotFather](https://t.me/botfather) on Telegram.
20
+
21
+ To use this server with MCP-compatible clients (like Claude Desktop, Agent_head, etc.), add it to your server configuration and pass the token as an environment variable:
22
+
23
+ ### Example `mcp_config.json`
24
+ ```json
25
+ {
26
+ "mcpServers": {
27
+ "agent-telegram-mcp": {
28
+ "command": "agent-telegram-mcp",
29
+ "env": {
30
+ "TELEGRAM_BOT_TOKEN": "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
31
+ }
32
+ }
33
+ }
34
+ }
35
+ ```
36
+
37
+ ## Available Tools
38
+
39
+ The server exposes the following tools to the LLM agent:
40
+
41
+ ### ✉️ Messaging
42
+ - **`telegram_send_message`**: Send text messages (supports Markdown, HTML, silent messages, and replies).
43
+ - **`telegram_forward_message`**: Forward existing messages between chats.
44
+ - **`telegram_delete_message`**: Delete a message from a chat (requires bot admin permissions).
45
+ - **`telegram_pin_message`**: Pin a message in a group/channel.
46
+
47
+ ### 🖼️ Media & Files
48
+ - **`telegram_send_photo`**: Send images via a local file path, public HTTP URL, or Telegram file ID.
49
+ - **`telegram_send_video`**: Send video files.
50
+ - **`telegram_send_audio`**: Send audio tracks (renders as a Telegram music player).
51
+ - **`telegram_send_voice`**: Send voice notes (`.ogg` files).
52
+ - **`telegram_send_document`**: Send arbitrary files (PDFs, ZIPs, code snippets, etc.).
53
+ - **`telegram_send_sticker`**: Send `.webp` stickers.
54
+ - **`telegram_send_location`**: Send a geographic map pin via latitude and longitude.
55
+
56
+ ### 📥 Retrieval & Info
57
+ - **`telegram_get_updates`**: Retrieve recent messages, commands, and callback queries sent to the bot (supports pagination with `offset` and `limit`).
58
+ - **`telegram_get_chat_info`**: Fetch detailed information about a user, group, or channel.
59
+ - **`telegram_get_chat_member_count`**: Check how many users are in a chat.
60
+ - **`telegram_get_file_info`**: Retrieve metadata and the download path for a file hosted on Telegram servers.
61
+ - **`telegram_download_file`**: Download a file to a specific local path or return its contents as a Base64 string.
62
+ - **`telegram_get_bot_info`**: Fetch the current bot's profile information to verify the token connection.
63
+
64
+ ## Development & Testing
65
+
66
+ You can run the server directly via standard I/O (stdio) transport:
67
+
68
+ ```bash
69
+ export TELEGRAM_BOT_TOKEN="your-token"
70
+ # On Windows: set TELEGRAM_BOT_TOKEN=your-token
71
+
72
+ agent-telegram-mcp
73
+ ```
agent_telegram_mcp-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,32 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "agent-telegram-mcp"
7
+ version = "0.1.0"
8
+ description = "Telegram MCP Server — lets AI agents send/receive Telegram messages via a Bot Token"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ keywords = ["mcp", "telegram", "bot", "ai", "stdio", "agent", "llm"]
13
+ authors = [
14
+ { name = "Tharindu Mendis" }
15
+ ]
16
+ urls = { Repository = "https://github.com/tharindumendis/Agent_telegeam_mcp" }
17
+
18
+ dependencies = [
19
+ "mcp[cli]>=1.0.0",
20
+ "httpx>=0.27.0",
21
+ "pydantic>=2.0.0",
22
+ "python-dotenv>=1.0.0",
23
+ ]
24
+
25
+ [project.scripts]
26
+ agent-telegram-mcp = "tele_bot_mcp.server:main"
27
+
28
+ [tool.hatch.build.targets.wheel]
29
+ packages = ["tele_bot_mcp"]
30
+
31
+ [dependency-groups]
32
+ dev = []
agent_telegram_mcp-0.1.0/requirements.txt ADDED
@@ -0,0 +1,3 @@
1
+ mcp[cli]>=1.0.0
2
+ httpx>=0.27.0
3
+ pydantic>=2.0.0
agent_telegram_mcp-0.1.0/tele_bot_mcp/__init__.py ADDED
File without changes