Telegram MCP Server for AI Agents
Metricgram wraps the Telegram Bot API as a hosted MCP server, so your AI agent can read, post, moderate and administer your Telegram groups with scoped keys and no bot code to maintain.
- 70+ Telegram Bot API methods as MCP tools
- Works with Claude, ChatGPT, Cursor and Codex
- Every call locked to your own groups
- Analytics, members and subscribers in the same server
No credit card required
Set up in 2 minutes
How it works
1
Add the bot and connect your groups
Add the Metricgram bot (or your own custom bot) to your Telegram groups as an admin. No servers, webhooks or polling to run.
2
Create a scoped API key
Generate an Elite API key and pick exactly what the agent may do, from read-only Telegram access to posting, moderation and chat settings.
3
Plug it into your AI client
Paste one config block into Claude, Cursor, Codex or any MCP client. Your agent now sees every allowed Telegram action as a tool.
One prompt, real Telegram actions
Your agent picks the right Bot API calls, Metricgram runs them against the right group and returns structured results.
metricgram · mcp
You ask
Post this week's AMA announcement in Crypto Talk, pin it quietly, open an "AMA questions" topic and give me an invite link that expires on Friday.
The agent calls
- send_telegram_message(group_id: 42, text: "…", buttons: [{ url: "…" }])
- pin_telegram_message(group_id: 42, action: "pin", disable_notification: true)
- manage_forum_topic(group_id: 42, action: "create", name: "…")
- create_telegram_invite_link(group_id: 42, expire_date: "2026-10-23T23:59:00Z")
Connect any MCP client
Use the hosted endpoint with your API key. Claude Desktop users can bridge it with mcp-remote.
{
"mcpServers": {
"metricgram": {
"url": "https://metricgram.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
Tools your agent gets
Messages and media
send_telegram_message
send_telegram_media
send_telegram_poll
edit_telegram_message
delete_telegram_messages
forward_telegram_message
react_to_telegram_message
Pins and forum topics
pin_telegram_message
manage_forum_topic
createForumTopic
closeGeneralForumTopic
unpinAllForumTopicMessages
Moderation and join requests
ban_member
restrict_member
promote_member
handle_telegram_join_request
banChatSenderChat
setChatAdministratorCustomTitle
Chat settings and invite links
update_telegram_chat_settings
create_telegram_invite_link
revokeChatInviteLink
setChatPermissions
setChatStickerSet
Analytics and community data
analytics_overview
active_users
list_members
list_messages
gamification_rankings
get_subscriber_health
Any supported Bot API method
telegram_api_methods
telegram_bot_api
get_telegram_chat
get_telegram_chat_member
The Telegram Bot API, wrapped for AI agents
Building a Telegram integration for an agent usually means hosting a bot, handling webhooks, storing tokens and writing a tool for every endpoint. Metricgram already runs the bot inside your groups, so your agent gets the Bot API as ready-made MCP tools from one hosted endpoint.
Typed tools plus a full Bot API gateway
Common jobs such as sending messages, media, polls, pins, topics and invite links have dedicated, well-described tools. Everything else goes through telegram_bot_api, which accepts official Bot API method names and parameters, so nothing in the supported catalog is out of reach.
Locked to your own groups
The agent never chooses a chat_id. Metricgram derives it from the group you own, checks forwarded and quoted messages against your other groups, and refuses anything that could reach another chat.
Scopes for every level of trust
Grant telegram:read for research agents, telegram:write for posting and topics, telegram:moderate for bans and join requests, and telegram:admin for titles, permissions and invite links. Keys can be revoked at any time.
Safe retries and clear errors
Write tools accept an idempotency key, so a retried call never posts twice. Telegram errors and rate limits come back as structured results with retry_after, which agents can handle on their own.
Context that raw bots do not have
The same server exposes Metricgram analytics, member history, captured messages, gamification, AI summaries and Stripe subscriber health, so your agent can decide what to do before it acts.
Metricgram vs. Manual Management
| Metricgram | Manual | |
|---|---|---|
| Hosted MCP endpoint, no bot server to run | ||
| 70+ Telegram Bot API methods as tools | ||
| chat_id locked to your own groups | ||
| Per-scope API keys you can revoke | ||
| Idempotent retries for write tools | ||
| Analytics and member history for context | ||
| Live chat data, admins and permissions | ||
| Works with your own custom bot |
Frequently Asked Questions
What is a Telegram MCP server?
It is a Model Context Protocol server that exposes Telegram actions as tools an AI agent can call. Metricgram hosts one for you, backed by the bot that already manages your groups.
Which AI clients does it work with?
Any client that speaks MCP over HTTP, including Claude Code, Claude Desktop (through mcp-remote), Cursor, Codex and custom agents built with the OpenAI or Anthropic SDKs.
Does it cover the whole Telegram Bot API?
It covers more than 70 group-related methods, including messages, media, polls, edits, reactions, pins, forum topics, moderation, join requests, chat settings and invite links. Methods that would affect other chats or the bot itself, such as webhooks, payments or leaving a group, are intentionally excluded.
Can an agent post in groups I do not own?
No. Every call is bound to one of your connected groups. The chat_id is set by Metricgram, and forwards or replies can only reference your own groups.
Is this the Telegram user API (MTProto)?
No. It uses the official Bot API through your group bot, so the agent acts as the bot, never as your personal Telegram account.
Which plan includes the MCP server?
MCP and API access are part of the Elite plan. The 14-day free trial includes Elite-level access, so you can connect an agent before paying.
Can I limit what the agent is allowed to do?
Yes. Each API key has its own scopes, and you can create separate keys for read-only research, posting, moderation and administration.
Keep exploring
Find a practical guide, browse active communities or discover more ways to use Metricgram.
Guides
Blog
Read practical playbooks on growth, monetization, moderation, and Telegram community operations.
ExploreCommunity directory
Telegram Communities Directory
Browse active Telegram communities by category, language, and positioning.
ExploreSection hub
Solutions
See every page in this section side by side.
ExploreExplore more
Telegram Group Management Tool
Telegram Group Analytics & Metrics
Telegram Bot for Group Management
Automate Your Telegram Group
Telegram Membership Bot for Paid Communities
Telegram Payment Bot for Groups and Channels
Telegram Subscription Bot for Recurring Revenue
Telegram Channel Monetization Made Simple
Create and Manage a Telegram VIP Group
Turn Telegram support into account intelligence
MCP
API
AI Chatbots Assistants