Most "Telegram MCP" servers connect an AI agent to Telegram itself: they read and send messages from your personal account or from a bot. That is a different job from running a shop. If you sell on Telegram, the MCP server you want is one that reaches your store's data: products, orders, customers, broadcasts and analytics. Tiny Shops runs one at https://mcp.tiny-shops.com/mcp. This guide explains the kinds of Telegram MCP servers, how to connect Claude Code, Cursor, Codex or another MCP client to your store in four steps, what to ask the agent, and how scripts call the same tools over HTTP.
Three kinds of Telegram MCP server#
| Kind | What the agent reaches | How it signs in | Typical use |
|---|---|---|---|
| Account MCP | Your personal chats and messages | Your Telegram account session | Reading and answering your own chats |
| Bot MCP | What one bot can see and send | A bot token | Sending messages and alerts through a bot |
| Store MCP (Tiny Shops) | One store: catalog, orders, customers, broadcasts, settings | Browser sign-in, you pick one store | Running the shop: orders, products, campaigns, reports |
Account servers are mostly community projects, and the agent acts as you in every chat. The Tiny Shops server does not touch your personal Telegram account. The agent works on one store, with the same rules and plan limits as the dashboard.
What you get#
One store, approved in the browser. The agent gets no password and can't see your other shops. You sign in with the account you already use and choose exactly one store. The approval screen spells out the limits: the agent can view and change operational data in that store, including products and orders; it cannot access billing or account settings, use admin-only actions, or reach your other stores.
Day-to-day work in plain language. Products, stock and variants, orders and shipping, customers and bonuses, promo codes, the theme, checkout and payment providers, the bot's welcome message, broadcasts, win-backs, the inbox and analytics are all tools.
A preview before anything wide goes out. A broadcast does not send on the first call: the agent comes back with the recipient count. Deletes and a currency change that relabels existing prices wait for an explicit yes.
The same tools for scripts and for Nano. Every tool is also POST https://mcp.tiny-shops.com/v1/<tool> with the same input, and the full contract is public at openapi.json. Nano, the assistant inside the dashboard, uses the same set of tools.
If the shop is not live yet, start with how to set up a Telegram store. The agent is most useful once there is a catalog and an order list to work on.
How to connect an AI agent to your Telegram store#
You need to be the store owner. Team members can't create this access.
- In the dashboard sidebar, open Agents & API.
- On the card Connect an AI agent, click Copy connection prompt.
- Paste that prompt into Claude Code, Cursor, Codex CLI, or VS Code with an MCP client that supports remote HTTP servers and browser sign-in.
- When the browser opens, sign in, pick one store, and click Connect.
The prompt the button copies is:
Connect to my Tiny Shops store using the MCP server at https://mcp.tiny-shops.com/mcp. Use browser OAuth; do not ask me for an API token.If the browser never opens, update the client: support for remote MCP changes quickly. Claude.ai and ChatGPT can add a custom connector with the same URL and complete the same browser sign-in. A normal chat with no connector will not connect just because you pasted the address.
What to ask#
Talk in sentences. The agent looks up the live tool list and fills in the ids. A few prompts that match what the server actually does:
Orders
- "List my 10 most recent paid orders."
- "Show me order 1042."
- "Mark order 1042 as paid." That status is
PROCESSING: paid and being prepared. - "Ship 1042 with DHL tracking JD014600003SE and tell the customer." Leave the last part off unless you want Tiny Shops to send the buyer the shipping message.
Catalog and storefront
- "Add a product called Mint Mug for 12.99."
- "Which promo codes are active?"
- "Switch the storefront primary color to mint green."
- "What's the welcome message? Rewrite it to mention free shipping over $40."
Numbers
- "How did the store do in the last 30 days?" The agent calls
get_analyticsfortoday,7d,30dor90dand gets revenue, orders, new customers, order counts by status, visitors and the top products, each compared with the period before.
Broadcasts
- "Send our new linen shirt to everyone as a product card with the text 'Back in stock'."
- "Schedule a message to customers who joined this week for Friday 10:00."
The agent can send to everyone, to specific customers, or to the dashboard's segments (new this week, recent buyers). A message can be text, a product card or a collection of 2 to 6 products. The first reply is always a preview: who would receive it and what it says. An immediate send goes to up to 500 people per call; a scheduled one has no such cap. Broadcasts count toward your plan's monthly limit (3, 10, 25 or unlimited). The same composer in the dashboard is explained in how to send a Telegram broadcast.
Win-backs
Win-backs need the Starter, Pro or Scale plan. Ask the agent to list them or create one: a title, a trigger (favorited or abandoned checkout), a wait of 0β30 days, a discount of 5β50%, a code that expires within 1β168 hours, the message, and up to two buttons. It is the same program as in the dashboard; see how to win back shoppers.
Bot token, currency and deletes#
Bot. Ask "is my bot connected?" any time. The answer is a yes or no plus the username; the token never comes back. Connecting a new BotFather token through the agent does the same work as the dashboard: it checks the token with Telegram and registers the store webhook. The token still passes through the chat to get there, so paste it in the dashboard when you can.
Currency and language. Reading them is safe. Changing the currency relabels prices already on products, so the agent must send a confirmation. Read the warning before you approve it.
Deletes. Deleting products, orders, promo codes or a custom domain needs an admin token, which a browser-connected agent never receives. Keep deletes in the dashboard, or use a short-lived admin token in a script and revoke it when the cleanup is done. Do not paste an admin token into an agent.
Scripts and warehouses#
Browser sign-in is the path for an assistant on your computer. A server-side script has no browser, so it uses an API token.
On Agents & API, click Create API token and pick Read (view store data) or Write (the same operational changes an agent gets). The token is shown once. Treat it like a password.
curl -X POST https://mcp.tiny-shops.com/v1/ship_order \
-H "Authorization: Bearer tsh_live_β¦" \
-H "Content-Type: application/json" \
-d '{"orderId": 1042, "carrier": "DHL", "trackingNumber": "JD014600003SE"}'Replace ship_order with any other tool name. get_analytics takes { "period": "30d" }. Responses look like { "ok": true, "data": β¦ } or { "ok": false, "error": { "code", "message" } }. Order changes also fire the store's signed order webhook, so a fulfillment system can react without polling. The full setup is in the developer guide: Connect an AI agent.
Each token gets 100 protocol calls a minute (listing tools, pings) and 30 tool calls a minute. A client that hits the cap gets a 429 with a wait time.
Disconnect it#
Open Agents & API β Agent connections, find the client, and click Disconnect. Its access and refresh tokens stop working immediately. API tokens are a separate list on the same page: Revoke the row, and that token stops too.
Connect the agent to the store you are actually working in. A second shop is a second approval, on purpose: one connection can't see both.
FAQ#
What is a Telegram MCP server? An MCP server gives an AI agent a set of tools it can call. A "Telegram MCP" server usually gives it tools for Telegram chats, through your account or a bot; most of the ones in MCP directories are third-party projects. The Tiny Shops server is the official one for Tiny Shops stores, and its tools work on your store's data, not your Telegram account.
Which AI clients work with it? Any MCP client that supports remote HTTP servers with browser sign-in: Claude Code, Cursor, Codex CLI, VS Code. Claude.ai and ChatGPT connect through a custom connector with the same URL.
Can the agent read my personal Telegram chats? No. It works with one store's data. Conversations in the store's inbox are reachable only through the inbox tools, and only for that store.
Do I need an API key? Not for an AI client: it signs in through the browser. API tokens are for scripts and servers that can't open a browser.
Can the agent delete my products or orders? No. Deleting products, orders, promo codes or a custom domain is admin-only, and a browser-connected agent never gets admin access. It also can't open billing or account settings.
Connect your agent to a store at tiny-shops.com β