telegra-me
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
telegra-me
MCP server that connects AI agents to your private Telegram bot — send notifications and ask questions while you are away from your computer.
Website
Website: https://guedes-joaofelipe.github.io/telegra-me/
Static product landing (website/), deployed to GitHub Pages on push to main. The site is available after the first successful workflow run and enabling Pages (source: GitHub Actions) in repository settings.
Related MCP server: mcp-telegram-agent
Problem
Long-running AI agents may need your input while you are away from your desk. telegra-me bridges MCP clients on your computer to Telegram on your phone so agents can notify you and wait for replies.
Prerequisites
uv — install dependencies with
uv syncafter cloningA Telegram bot and chat ID — follow docs/SETUP.md
Configuration reference: docs/CONFIG.md
Quick start
git clone <repository-url>
cd telegra-me
uv sync
cp config.example.yml config.yml
# Edit config.yml with your Telegram token, chat ID, and API key
make serveThe daemon listens on http://127.0.0.1:8765/mcp by default.
Background service
Install a user service that starts at login (no terminal required):
uv sync
make service-installCommand | Purpose |
| Install and start launchd (macOS) or systemd user service (Linux) |
| Stop and remove the service |
| Print whether the daemon is running |
Logs on macOS: ~/Library/Logs/telegra-me/stdout.log and stderr.log.
On Linux, enable lingering if the service must run without an active session:
loginctl enable-linger "$USER"MCP clients
telegra-me is not Cursor-specific. The daemon speaks standard MCP over HTTP on loopback with Bearer API key auth. Start it first with make serve or make service-install.
Cursor
~/.cursor/mcp.json or project .cursor/mcp.json:
{
"mcpServers": {
"telegra-me": {
"url": "http://127.0.0.1:8765/mcp",
"headers": {
"Authorization": "Bearer YOUR_MCP_API_KEY"
}
}
}
}Claude Code (CLI)
claude mcp add --transport http telegra-me http://127.0.0.1:8765/mcp \
--header "Authorization: Bearer YOUR_MCP_API_KEY"Claude Desktop
Local Claude Desktop config is stdio-only. Use mcp-remote to bridge stdio → the running HTTP daemon (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"telegra-me": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://127.0.0.1:8765/mcp",
"--transport",
"http-only",
"--header",
"Authorization:${MCP_API_KEY_HEADER}"
],
"env": {
"MCP_API_KEY_HEADER": "Bearer YOUR_MCP_API_KEY"
}
}
}
}Replace YOUR_MCP_API_KEY with server.api_key from config.yml or the MCP_API_KEY environment variable.
Note: Claude Custom Connectors (cloud-brokered remote MCP) require a public HTTPS URL and do not work with a localhost-only daemon.
MCP tools
Tool | Purpose |
| One-way text notification |
| Send an image (HTTPS URL or local absolute path) |
| Send an audio track with optional title/performer |
| Send a voice note (OGG/OPUS recommended) |
| Ask a question and wait for a reply (text, photo, audio, or voice) |
Media source rules:
Provide exactly one of
*_url(HTTPS only) or*_path(absolute local file path) per callask_telegram_useraccepts optionalphoto_url/photo_pathto attach an image; the question becomes the captionAnswered
ask_telegram_userresponses includereply_type(text,photo,audio, orvoice); media replies include Telegramfile_id(bytes are not downloaded back to the agent)
Voice notes work best as OGG files with OPUS encoding (Telegram’s native voice format).
Troubleshooting
Symptom | Check |
Daemon exits immediately |
|
MCP client cannot connect | Daemon running? ( |
HTTP 401 from MCP client |
|
Telegram messages not received | Bot token valid? |
| Reply with a text, photo, audio, or voice message from the allowlisted chat while the tool is waiting |
Media send fails after upgrade | Restart the background service ( |
Linux service stops at logout | Run |
Development
make lint
make tests
make coverageFeature specs: docs/specs/features/core-platform/, docs/specs/features/media-messaging/.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Unofficial Telegram MCP server — read, search, reply and react in your own Telegram account.
Schedule posts, read analytics and manage Telegram channels in TGStudio from any MCP client.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
Related MCP Servers
- FlicenseAqualityAmaintenanceBridges AI assistants to a Telegram bot to enable two-way messaging, interactive confirmations, and live status updates. It supports automatic voice transcription via local Whisper models and provides secure, single-user communication for MCP-compatible hosts.46-
- AlicenseBqualityDmaintenanceSends Telegram notifications and supports onboarding, updates, and control replies via MCP tools from any AI agent.629 npm2MIT
- AlicenseNot gradedqualityDmaintenanceBidirectional bridge between Telegram and MCP-compatible agents, allowing agents to poll for new messages and send replies through Telegram, without any built-in language model.MIT
- AlicenseNot gradedqualityDmaintenanceEnables sending and receiving Telegram messages through MCP clients like Claude Desktop and Gemini Spark.35 npmMIT