Telegram MCP server, early access

Your AI agent, on your own Telegram.

Q: Does it work with ChatGPT or Cursor?

Cursor works: add the server to ~/.cursor/mcp.json with its URL and an X-API-Key header. Claude Code, Claude desktop, Codex and OpenClaw work too, as does any MCP client that can send a header over Streamable HTTP. ChatGPT connectors do not work yet, because they cannot send a key header; sign in is planned.

telemcp logs in to your own Telegram account, not a bot. Your agent in Claude, Cursor, Codex or OpenClaw reads and answers your private chats as you.

Your own account, not a bot. Nothing to host. End the session anytime in Telegram.
Invite only for now; prices are not published yet.

The whole install, in Claude Code

claude mcp add --transport http telemcp "$TELEMCP_URL" --header "X-API-Key: $TELEMCP_API_KEY"

Lena Vogelonline

Yesterday

Demo deck.pdf2.4 MB

18:20

Sent over the deck. Have a look when you get a minute.18:20

Today

Hey! Still on for the demo this week? Which day suits you?09:41

Thursday at 10:00 works for me. I’ll send the link that morning.09:42

~/inbox claude

✻ Claude Code MCP: telemcp connected

> Check my Telegram. If Lena asks about the demo, tell her Thursday 10:00 works.

⏺Checked Telegram, 1 new messagewait_for_messages

⎿Lena: “Still on for the demo this week? Which day suits you?”

⏺Replied to Lena, from your accountsend_message

⏺Checked delivery: readget_message

⏺Done. Lena asked about the demo and I told her Thursday 10:00 works. She has read it.

1 Lena writes on Telegram
2 Your agent reads it
3 It answers as you

Lena wrote at 09:41. A minute later she had her answer, sent from your own Telegram account by the agent you already use, and she read it.

Works with

Claude Code
Claude desktop
Cursor
Codex
OpenClaw
Any MCP client that sends a header
ChatGPT: not yet

What your agent gets done on Telegram.

Three jobs, from your own account: hear every new message, answer it with the right file, and follow up without nagging.

⏺Checked Telegram: 4 new in 3 chats. Starting with Daniel.

It hears every new private message

One call waits up to 55 seconds and takes up to 50 messages. Messages that land while your agent is closed are kept, and its cursor picks them up next time. No server to run.

wait_for_messages

It answers as you, with the file they asked for

Up to 4,096 characters plus one photo, video, audio file or document, in the chat they started. It writes to people already in your contacts.

send_message

Follow up of 10:02

Sent10:02

Delivered10:02

Read10:46

It follows up, then waits for a reply

It sees whether each message was sent, delivered or read, or why it failed. After 3 messages to someone who has not replied, sends to them hold until they answer.

get_message

From invite to first message in about a minute.

One key, one config, one sentence to your agent. No bot to create, nothing to host.

01
Get your invite
Your invite carries your API key and the server URL. Put them in environment variables so the key never sits in a file you commit.
02
Paste one config
Add the server to your MCP client. It speaks Streamable HTTP and takes the key in the X-API-Key header.
03
Tell your agent to log in
“Connect my Telegram account +31…”. Telegram sends a login code to your Telegram app; give it to your agent. Prefer a QR code? Scan it under Settings, Devices, Link Desktop Device.
04
Send the first message
“Tell Marco the invoice went out.” It goes out from your account, to someone already in your contacts.

Terminal

export TELEMCP_API_KEY="paste your key here"
export TELEMCP_URL="paste the server URL here"
claude mcp add --transport http telemcp "$TELEMCP_URL" \
  --header "X-API-Key: $TELEMCP_API_KEY"

Add --scope user to have it in every project. Then type /mcp in Claude Code to see the tools.

claude_desktop_config.json

{
  "mcpServers": {
    "telemcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "<server URL from your invite>",
               "--header", "X-API-Key:${TELEMCP_API_KEY}"],
      "env": { "TELEMCP_API_KEY": "paste your key here" }
    }
  }
}

Claude desktop reaches the server through the mcp-remote bridge, which needs Node.js. Quit and reopen Claude after saving.

~/.cursor/mcp.json

{
  "mcpServers": {
    "telemcp": {
      "url": "<server URL from your invite>",
      "headers": { "X-API-Key": "${env:TELEMCP_API_KEY}" }
    }
  }
}

Restart Cursor and turn the tools on under its MCP settings.

Terminal

codex mcp add telemcp --url "$TELEMCP_URL" \
  --bearer-token-env-var TELEMCP_API_KEY

Works in the Codex CLI, the IDE extension and the app.

OpenClaw config, mcp.servers

{
  mcp: { servers: { telemcp: {
    url: "<server URL from your invite>",
    transport: "streamable-http",
    headers: { "X-API-Key": "${TELEMCP_API_KEY}" },
  } } },
}

Or add it in the Control UI under Settings, MCP. Check it with openclaw mcp doctor telemcp --probe. Use OpenClaw 2026.5.12 or later.

ChatGPT connectors cannot send an API key header yet, so telemcp does not work in ChatGPT today. Sign in for ChatGPT is planned. Any other MCP client that can send a header over Streamable HTTP works now.

Your agent

Connect my Telegram account +31 6 1234 5678

Telegram sent a login code to your Telegram app. What is it?

52917

Connected. I can read and answer your private chats now.

Telegramservice notifications

One session, start to finish.

Inside Claude Code: log in, send the first message, check delivery. Every tool answer starts with its HTTP status.

~/inbox claude

> connect my Telegram account +31 6 1234 5678

⏺telemcp · connect_telegram (MCP)(body: {"phone_number": "+31612345678"})

⎿HTTP 200 {"status": "code_required", ...}

⏺Telegram sent a login code to your Telegram app. What is it?

> 52917

⏺telemcp · submit_telegram_code (MCP)

⎿HTTP 200 {"status": "connected", ...}

> tell Marco the invoice went out this morning

⏺telemcp · send_message (MCP)(body: {"to": {"phone": "+393401234567"}, "text": "Hi Marco, the invoice went out this morning."})

⎿HTTP 202 {"id": "Qe7rT2yU9iO1pA4sD6fG", ...}

⏺telemcp · get_message (MCP)

⎿HTTP 200 {"status": "delivered", ...}

⏺Sent to Marco from your account. Delivered.

Login codeArrives in your Telegram app, like any new login. Two step verification on? The agent asks for your password next.
A new deviceThe session shows up in Telegram under Settings, Devices. End it there whenever you like, or ask your agent to disconnect.
Existing contactsMarco is already in your contacts. A stranger by username is refused for now.
Status you can trustSent, delivered, read, or failed with the reason.

Put your agent on Telegram.

Invite only for now. Your API key comes with the invite; prices are not published yet.

Your account, not a bot.

A Telegram bot is a separate account that people have to find and start before it can talk to them. telemcp logs in as you, like the Telegram app on a new device, so your agent works inside the chats you already have.

A Telegram bottelemcp

Talks asBot: a separate bot with its own nametelemcp: you, from your own account

Where chats happenBot: a new chat with the bottelemcp: your existing private chats

Who it can write toBot: people who started the bottelemcp: people already in your contacts

SetupBot: create a bot, run code for its updatestelemcp: log in with a code or QR, paste one config

Groups and channelsBot: yestelemcp: no, private chats only

The tools your agent calls.

You talk to your agent in plain words; it picks these itself. Tools that take a request body get it in one body argument. Type /mcp in Claude Code to see the full list.

What it doesToolTakes

Log in to Telegramconnect_telegramphone_number, mode code or qr

Finish the login

submit_telegram_code
submit_telegram_password

the code Telegram sent; your password if two step verification is on

See the account and today’s limitslist_accountsnothing

Hear new messageswait_for_messagestimeout_s up to 55, cursor

Reply or write to a contactsend_messageto.phone or to.contact_id, text, media_url

Check deliveryget_messagethe message id

Know what is left todayget_usagenothing

Log outdisconnect_telegramthe phone number

Push events to your servercreate_webhookurl, subscribed_to, name

Read earlier messagesGET /messagesREST only, newest first, up to 100 per call

Same thing over plain HTTPS

# wait for the next Telegram message
curl "$TELEMCP_API_URL/messages/wait?timeout_s=25" \
  -H "X-API-Key: $TELEMCP_API_KEY"

# HTTP 200, nothing new yet
{
  "messages": [],
  "cursor": "2026-10-17T03:52:22.191Z|"
}

Pass the cursor back on the next call and nothing is missed or repeated. The same wait is what your agent runs through MCP.

Or let events come to you

Webhooks post to a public https address of yours, signed with HMAC SHA‑256 in X-Webhook-Signature. Send a test event, watch delivery health, re‑enable after a pause.

message.received
message.sent
message.delivered
message.read
message.failed
account.connected
account.disconnected
account.restricted
account.limit_reached

Your agent decides what to say. telemcp only delivers it.

telemcp never writes or sends a message on its own. Every word comes from the agent you set up, with the instructions you gave it.

“Will Telegram flag my account?”

Nobody can promise an account will never be restricted. Telegram has its own spam rules for user accounts, and it acts on accounts that message strangers. Answering people who write to you is the safe way to use it.

So the limits sit on the server, apply to every account, and no setting turns them off.

Early access limits, per account
Connected Telegram accounts	1
Messages sent per day	50
New contacts per day	10
Messages to one person who has not replied	3, then it waits
Same first message to more than 5 people within 30 minutes	Sending stops for review
Someone replies STOP	No more messages to them
Telegram asks the account to slow down	Sends pause
Telegram flags the account for messaging strangers	Sending stops

Source: the server side checks every send passes in early access. A day is one UTC day; a refused send says when to retry.

What it will not do

Write or send anything on its own. Every message comes from your agent.
Start a chat with a stranger by username. Only people already in your contacts.
Work in groups or channels. Private chats only.
Send in bulk. It is not a mass messaging tool, and the caps make sure of it.
Create Telegram accounts or act as a bot. It uses your existing account.

How you stay in control

End the session from Telegram itself: Settings, Devices.
Or ask your agent to disconnect your Telegram account.
Your chats stay in your Telegram app, where you read and answer them yourself as always.
Your agent can ask how many messages and new contacts it has left today.
Your Telegram connection is stored encrypted and used only to send and receive the messages your agent asks for.

Questions people search for.

Short answers. The rest is in the setup above.

What is a Telegram MCP server?

A Telegram MCP server gives an AI agent tools to read and send Telegram messages through the Model Context Protocol. telemcp is one: your agent can wait for new messages, reply or write to a contact, check whether a message was delivered or read, and see how many sends it has left today. Your agent decides what to say; telemcp never writes or sends a message on its own.

Is there a Telegram MCP server that uses my own account, not a bot?

Yes. telemcp logs in to your existing Telegram account, like the Telegram app on a new device. It does not use the Bot API, so your agent reads and answers your private chats as you. You log in with the code Telegram sends to your Telegram app, or by scanning a QR code under Settings, Devices, Link Desktop Device. You can end the session there at any time.

How much does telemcp cost?

Prices are not published yet. Early access is invite only, and your API key comes with the invite. Leave your email on this page to get one when a spot opens.

How do I connect Claude to Telegram?

In Claude Code, run one command with the server URL and API key from your invite: claude mcp add --transport http telemcp "$TELEMCP_URL" --header "X-API-Key: $TELEMCP_API_KEY". Then ask Claude to connect your Telegram account with your phone number and tell it the login code Telegram sends you. Claude desktop works through the mcp-remote bridge in claude_desktop_config.json, which needs Node.js.

Can my AI agent message people who never wrote to me on Telegram?

Not yet. Your agent can message people who are already a contact on your account, for example someone who wrote to you. Starting a chat with a new person by username is refused for now. Answering people who write to you is also the safe way to use a Telegram account with an agent.

Can it message Telegram groups or channels?

No. telemcp works in your private chats only. Groups and channels are not supported.

Does it work with ChatGPT or Cursor?

Cursor works: add the server to ~/.cursor/mcp.json with its URL and an X-API-Key header. Claude Code, Claude desktop, Codex and OpenClaw work too, as does any MCP client that can send a header over Streamable HTTP. ChatGPT connectors do not work yet, because they cannot send a key header; sign in is planned.

Do I need a server or webhooks to receive Telegram messages?

No. Your agent calls wait_for_messages, which stays open for up to 55 seconds and answers the moment a message arrives, up to 50 at a time. Messages that arrive while the agent is closed are stored, and an agent that kept its cursor picks them up on its next call. Webhooks are there if you want events pushed to your own server: 9 event types, signed with HMAC SHA-256.

Give your agent your Telegram inbox, not your evenings.

Early access is invite only. Leave your email and we write to you when a spot opens; your API key comes with the invite. Prices are not published yet.

Your own account, not a bot. Nothing to host. End the session anytime in Telegram.