| Name | simple-telegram-mcp JSON |
| Version |
0.1.9
JSON |
| download |
| home_page | None |
| Summary | The simplest MCP server for interacting with Telegram |
| upload_time | 2025-09-17 11:34:17 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
automation
http
llm
mcp
telegram
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<a id="top"></a>
<div align="center">
<a href="https://github.com/elyase/simple-telegram-mcp">
<img src="logo.png" alt="Logo" width="110" height="110">
</a>
<h1>Simple Telegram MCP</h1>
</div>
## ✨ Example use cases
- **Automate tasks**: “Look up the weather forecast and send it to my family group”
- **Stay on top of things**: “Review my unread messages, give me the highlights, and queue polite replies”
- **Polish before sending**: “Read Tony’s latest note in the Family channel, craft three informal reply drafts, and leave them for me to send.”
## 🚀 Quick Start
### Automatic client configuration
| Client | Command |
|-------------------|---------------------------------------------------|
| Cursor | `uvx simple-telegram-mcp --install cursor` |
| Claude Desktop | `uvx simple-telegram-mcp --install claude-desktop`|
| Claude Code | `uvx simple-telegram-mcp --install claude-code` |
| Gemini CLI | `uvx simple-telegram-mcp --install gemini-cli` |
| VS Code (global) | `uvx simple-telegram-mcp --install vscode` |
| MCP JSON (stdout) | `uvx simple-telegram-mcp --install mcp-json` |
| OpenAI Codex CLI | `uvx simple-telegram-mcp --install codex-cli` |
### Authorize Telegram
```bash
uvx simple-telegram-mcp --login
```
>
> ✨ Heads-up: the login flow is zero drama. You’ll pop in your phone number, Telegram will DM you a code, you paste it back here, and you’re in.
## 🛠️ Tools
| Tool | Description |
|--------------------------|-----------------------------------------------------------------------------|
| `telegram_add_reaction` | Adds an emoji reaction to a specific message. |
| `telegram_get_chat_history` | Retrieves recent messages for a chat. |
| `telegram_get_draft` | Returns the current unsent draft for a chat, if one exists. |
| `telegram_get_user_profile` | Fetches profile information for a user. |
| `telegram_list_chats` | Lists dialogs (DMs, groups, channels) the account can access. |
| `telegram_login_status` | Reports connection and authorization status. |
| `telegram_post_message` | Sends a new message to a chat. |
| `telegram_reply_to_message` | Replies to a message by ID. |
| `telegram_save_draft` | Stores or updates a draft message without sending it. |
| `telegram_search_chats` | Finds chats by partial name or username. |
| `search_telegram_messages` | Searches globally (or within a chat) for messages containing text. |
## 🧾 Resources
| Resource URI | Description |
|-----------------------------------|---------------------------------------------------------------|
| `telegram://chats` | Latest 25 dialogs with names, types, and unread counts. |
| `telegram://session/status` | Connection and authorization snapshot. |
| `telegram://chats/{chat_id}/unread` | Incoming unread messages for a chat (oldest first). |
| `telegram://chats/{chat_id}/history` | Recent message history for a chat. |
## 🧠 Prompts
- `telegram/draft-reply` – Generates a concise reply in the tone you request.
- `telegram/check-session` – Reminds the assistant to verify the session before doing anything else.
## ✅ Testing
- Fast unit tests (default): `uv run pytest -q`
- Integration tests: `RUN_TELEGRAM_TESTS=1 uv run pytest -m integration -q` (make sure to log in first: `uvx simple-telegram-mcp --login`)
<p align="right">(<a href="#top">back to top</a>)</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "simple-telegram-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Yaser Martinez Palenzuela <yaser.martinez@gmail.com>",
"keywords": "automation, http, llm, mcp, telegram",
"author": null,
"author_email": "Yaser Martinez Palenzuela <yaser.martinez@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6d/ef/daee2e18affc391bee95c83e9e3dae3786d955993ff438b5808bc2053446/simple_telegram_mcp-0.1.9.tar.gz",
"platform": null,
"description": "<a id=\"top\"></a>\n\n<div align=\"center\">\n <a href=\"https://github.com/elyase/simple-telegram-mcp\">\n <img src=\"logo.png\" alt=\"Logo\" width=\"110\" height=\"110\">\n </a>\n\n <h1>Simple Telegram MCP</h1>\n</div>\n\n## \u2728 Example use cases\n\n- **Automate tasks**: \u201cLook up the weather forecast and send it to my family group\u201d\n- **Stay on top of things**: \u201cReview my unread messages, give me the highlights, and queue polite replies\u201d\n- **Polish before sending**: \u201cRead Tony\u2019s latest note in the Family channel, craft three informal reply drafts, and leave them for me to send.\u201d\n\n\n## \ud83d\ude80 Quick Start\n\n### Automatic client configuration\n\n| Client | Command |\n|-------------------|---------------------------------------------------|\n| Cursor | `uvx simple-telegram-mcp --install cursor` |\n| Claude Desktop | `uvx simple-telegram-mcp --install claude-desktop`|\n| Claude Code | `uvx simple-telegram-mcp --install claude-code` |\n| Gemini CLI | `uvx simple-telegram-mcp --install gemini-cli` |\n| VS Code (global) | `uvx simple-telegram-mcp --install vscode` |\n| MCP JSON (stdout) | `uvx simple-telegram-mcp --install mcp-json` |\n| OpenAI Codex CLI | `uvx simple-telegram-mcp --install codex-cli` |\n\n### Authorize Telegram\n\n```bash\nuvx simple-telegram-mcp --login\n```\n\n>\n> \u2728 Heads-up: the login flow is zero drama. You\u2019ll pop in your phone number, Telegram will DM you a code, you paste it back here, and you\u2019re in.\n\n## \ud83d\udee0\ufe0f Tools\n\n| Tool | Description |\n|--------------------------|-----------------------------------------------------------------------------|\n| `telegram_add_reaction` | Adds an emoji reaction to a specific message. |\n| `telegram_get_chat_history` | Retrieves recent messages for a chat. |\n| `telegram_get_draft` | Returns the current unsent draft for a chat, if one exists. |\n| `telegram_get_user_profile` | Fetches profile information for a user. |\n| `telegram_list_chats` | Lists dialogs (DMs, groups, channels) the account can access. |\n| `telegram_login_status` | Reports connection and authorization status. |\n| `telegram_post_message` | Sends a new message to a chat. |\n| `telegram_reply_to_message` | Replies to a message by ID. |\n| `telegram_save_draft` | Stores or updates a draft message without sending it. |\n| `telegram_search_chats` | Finds chats by partial name or username. |\n| `search_telegram_messages` | Searches globally (or within a chat) for messages containing text. |\n\n## \ud83e\uddfe Resources\n\n| Resource URI | Description |\n|-----------------------------------|---------------------------------------------------------------|\n| `telegram://chats` | Latest 25 dialogs with names, types, and unread counts. |\n| `telegram://session/status` | Connection and authorization snapshot. |\n| `telegram://chats/{chat_id}/unread` | Incoming unread messages for a chat (oldest first). |\n| `telegram://chats/{chat_id}/history` | Recent message history for a chat. |\n\n## \ud83e\udde0 Prompts\n\n- `telegram/draft-reply` \u2013 Generates a concise reply in the tone you request.\n- `telegram/check-session` \u2013 Reminds the assistant to verify the session before doing anything else.\n\n\n## \u2705 Testing\n\n- Fast unit tests (default): `uv run pytest -q`\n- Integration tests: `RUN_TELEGRAM_TESTS=1 uv run pytest -m integration -q` (make sure to log in first: `uvx simple-telegram-mcp --login`)\n\n<p align=\"right\">(<a href=\"#top\">back to top</a>)</p>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The simplest MCP server for interacting with Telegram",
"version": "0.1.9",
"project_urls": null,
"split_keywords": [
"automation",
" http",
" llm",
" mcp",
" telegram"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9987d7cba2071d8645c1ae1c2abca123b0b7074a88a9f25a3aebe53f6de076a0",
"md5": "3d85afc8b2aa5b86e82537de02a41a43",
"sha256": "95b4b9652ba11981f2fe60cef9b4ff191b657c62ed67549dd4e784009e33794a"
},
"downloads": -1,
"filename": "simple_telegram_mcp-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d85afc8b2aa5b86e82537de02a41a43",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16590,
"upload_time": "2025-09-17T11:34:16",
"upload_time_iso_8601": "2025-09-17T11:34:16.547705Z",
"url": "https://files.pythonhosted.org/packages/99/87/d7cba2071d8645c1ae1c2abca123b0b7074a88a9f25a3aebe53f6de076a0/simple_telegram_mcp-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6defdaee2e18affc391bee95c83e9e3dae3786d955993ff438b5808bc2053446",
"md5": "e8a21a4cd27e09183b68885289a46c88",
"sha256": "9267af2f7c0e01e92997e8656f97b5d1304ebb3a03fdbcab4a030d8b0398d928"
},
"downloads": -1,
"filename": "simple_telegram_mcp-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "e8a21a4cd27e09183b68885289a46c88",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 1295560,
"upload_time": "2025-09-17T11:34:17",
"upload_time_iso_8601": "2025-09-17T11:34:17.453407Z",
"url": "https://files.pythonhosted.org/packages/6d/ef/daee2e18affc391bee95c83e9e3dae3786d955993ff438b5808bc2053446/simple_telegram_mcp-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-17 11:34:17",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "simple-telegram-mcp"
}
