{"_id":"telegram-mcp-connect","_rev":"4-8f0948c83439e0f94ed6041d5b16569f","name":"telegram-mcp-connect","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"telegram-mcp-connect","version":"0.1.0","keywords":["telegram","telegram-mcp","mcp","mcp-server","modelcontextprotocol","model-context-protocol","claude","claude-code","codex","cursor","windsurf","telegram-client","mtproto","ai-agent","chat"],"license":"MIT","_id":"telegram-mcp-connect@0.1.0","maintainers":[{"name":"sharathxct","email":"sharathxct@gmail.com"}],"homepage":"https://github.com/sharathxct/telegram-mcp-connect#readme","bugs":{"url":"https://github.com/sharathxct/telegram-mcp-connect/issues"},"bin":{"telegram-mcp-connect":"dist/cli.js"},"dist":{"shasum":"08870d6b313b4a8545789db87ccca70b10fec451","tarball":"https://registry.npmjs.org/telegram-mcp-connect/-/telegram-mcp-connect-0.1.0.tgz","fileCount":4,"integrity":"sha512-Mz9mgHM788ZHHShx7wpuZjIC55i+5L1DshnDuOXXRRCD9Gw55s9dJK3iC/x9FJwhYn2FX6NOttEkurzjTwZc0A==","signatures":[{"sig":"MEUCIQCI5lu+qes4G/ke+kNutRY/HehzigXw9/c2/U+bNliA3gIgOpsqesdx4sv4Vf7jgsctYQZrhHrryUBBhAfQFecuFug=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":50397},"type":"module","engines":{"node":">=18"},"gitHead":"30c99a2c1ebf9cc539d8f6482bd21517ccb0bd83","scripts":{"dev":"bun bin/cli.ts","test":"bun test","build":"bun build ./bin/cli.ts --target=node --outdir=dist --packages=external --format=esm --banner='#!/usr/bin/env node' && chmod +x dist/cli.js","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"_npmUser":{"name":"sharathxct","email":"sharathxct@gmail.com"},"overrides":{"fast-uri":"3.1.4","@hono/node-server":"2.0.12"},"repository":{"url":"git+https://github.com/sharathxct/telegram-mcp-connect.git","type":"git"},"_npmVersion":"11.6.1","description":"Telegram MCP server that runs locally. Connect Telegram to Claude Code, Codex, Cursor and other MCP clients to read chats, search messages and summarise conversations. Your session stays on your machine.","directories":{},"_nodeVersion":"24.10.0","dependencies":{"teleproto":"^1.228.4","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"packageManager":"bun@1.2.22","devDependencies":{"@types/bun":"1.3.14","typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-connect_0.1.0_1785372398463_0.9648885631133082","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"telegram-mcp-connect","version":"0.1.1","keywords":["telegram","telegram-mcp","mcp","mcp-server","modelcontextprotocol","model-context-protocol","claude","claude-code","codex","cursor","windsurf","telegram-client","mtproto","ai-agent","chat"],"license":"MIT","_id":"telegram-mcp-connect@0.1.1","maintainers":[{"name":"sharathxct","email":"sharathxct@gmail.com"}],"homepage":"https://github.com/sharathxct/telegram-mcp-connect#readme","bugs":{"url":"https://github.com/sharathxct/telegram-mcp-connect/issues"},"bin":{"telegram-mcp-connect":"dist/cli.js"},"dist":{"shasum":"89dd305d7ef9f090256984be0cb24edb4915b7a1","tarball":"https://registry.npmjs.org/telegram-mcp-connect/-/telegram-mcp-connect-0.1.1.tgz","fileCount":4,"integrity":"sha512-Fs42OzndEGIQpl7swnReaw3vxd8WUXyOpgoDoVLp+Mi5CzggxlfMbeqHH7LFZ3XDnd35SQQ9NNmVXXJwPjRQ8w==","signatures":[{"sig":"MEYCIQDWUs+e2Z5ANaQAVYusEjoE5dXskuFdCjnIz+i1Ij8ugQIhAP0A/e98YgSQqZOzCUjdhzDh5QiISY9BEbGs1DeiQ7ok","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48370},"type":"module","engines":{"node":">=18"},"gitHead":"ef339b3da3f14a1778b30bc2969148b636fa50ec","scripts":{"dev":"bun bin/cli.ts","test":"bun test","build":"bun build ./bin/cli.ts --target=node --outdir=dist --packages=external --format=esm --banner='#!/usr/bin/env node' && chmod +x dist/cli.js","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"_npmUser":{"name":"sharathxct","email":"sharathxct@gmail.com"},"overrides":{"fast-uri":"3.1.4","@hono/node-server":"2.0.12"},"repository":{"url":"git+https://github.com/sharathxct/telegram-mcp-connect.git","type":"git"},"_npmVersion":"11.6.1","description":"Telegram MCP server that runs locally. Connect Telegram to Claude Code, Codex, Cursor and other MCP clients to read chats, search messages and summarise conversations. Your session stays on your machine.","directories":{},"_nodeVersion":"24.10.0","dependencies":{"teleproto":"^1.228.4","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"packageManager":"bun@1.2.22","devDependencies":{"@types/bun":"1.3.14","typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-connect_0.1.1_1785373667133_0.4034280456683519","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"telegram-mcp-connect","version":"0.1.2","keywords":["telegram","telegram-mcp","mcp","mcp-server","modelcontextprotocol","model-context-protocol","claude","claude-code","codex","cursor","windsurf","telegram-client","mtproto","ai-agent","chat"],"license":"MIT","_id":"telegram-mcp-connect@0.1.2","maintainers":[{"name":"sharathxct","email":"sharathxct@gmail.com"}],"homepage":"https://github.com/sharathxct/telegram-mcp-connect#readme","bugs":{"url":"https://github.com/sharathxct/telegram-mcp-connect/issues"},"bin":{"telegram-mcp-connect":"dist/cli.js"},"dist":{"shasum":"fa830186060f65829f1aadd83725209852406ca5","tarball":"https://registry.npmjs.org/telegram-mcp-connect/-/telegram-mcp-connect-0.1.2.tgz","fileCount":4,"integrity":"sha512-6sMAZfkTGVMySuG+2BOj5iH1iIwVYLg5/ZzyJKuWlJr4d3pQ1KaHUQAkTr+ne2z9WEYysa3wxPFybfJZukfvLA==","signatures":[{"sig":"MEUCIQCLxZfZuS98xwnMWwkIF0NRJxMvMY9h/OQFYU8DxSEK9QIgZZ3rzACw0SEP8SwSm2ZmGsc82wvC/SIQgxXQ84Bu8YA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46285},"type":"module","engines":{"node":">=18"},"gitHead":"db66468a47bb41b29cd44aacb1cdbeafeb146c12","scripts":{"dev":"bun bin/cli.ts","test":"bun test","build":"bun build ./bin/cli.ts --target=node --outdir=dist --packages=external --format=esm --banner='#!/usr/bin/env node' && chmod +x dist/cli.js","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"_npmUser":{"name":"sharathxct","email":"sharathxct@gmail.com"},"overrides":{"fast-uri":"3.1.4","@hono/node-server":"2.0.12"},"repository":{"url":"git+https://github.com/sharathxct/telegram-mcp-connect.git","type":"git"},"_npmVersion":"11.6.1","description":"Telegram MCP server that runs locally. Connect Telegram to Claude Code, Codex, Cursor and other MCP clients to read chats, search messages and summarise conversations. Your session stays on your machine.","directories":{},"_nodeVersion":"24.10.0","dependencies":{"teleproto":"^1.228.4","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"packageManager":"bun@1.2.22","devDependencies":{"@types/bun":"1.3.14","typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/telegram-mcp-connect_0.1.2_1785374723990_0.07036456512474643","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"telegram-mcp-connect","version":"0.1.3","description":"Telegram MCP server that runs locally. Connect Telegram to Claude Code, Codex, Cursor and other MCP clients to read chats, search messages and summarise conversations. Your session stays on your machine.","license":"MIT","type":"module","packageManager":"bun@1.2.22","homepage":"https://github.com/sharathxct/telegram-mcp-connect#readme","repository":{"type":"git","url":"git+https://github.com/sharathxct/telegram-mcp-connect.git"},"bugs":{"url":"https://github.com/sharathxct/telegram-mcp-connect/issues"},"bin":{"telegram-mcp-connect":"dist/cli.js"},"engines":{"node":">=18"},"keywords":["telegram","telegram-mcp","mcp","mcp-server","modelcontextprotocol","model-context-protocol","claude","claude-code","codex","cursor","windsurf","telegram-client","mtproto","ai-agent","chat"],"scripts":{"build":"bun build ./bin/cli.ts --target=node --outdir=dist --packages=external --format=esm --banner='#!/usr/bin/env node' && chmod +x dist/cli.js","dev":"bun bin/cli.ts","test":"bun test","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"devDependencies":{"@types/bun":"1.3.14","typescript":"^5"},"dependencies":{"@modelcontextprotocol/sdk":"^1.30.0","teleproto":"^1.228.4"},"overrides":{"@hono/node-server":"2.0.12","fast-uri":"3.1.4"},"gitHead":"6a682e4e683b88dcc8e4bd0d040548aea80c70ff","_id":"telegram-mcp-connect@0.1.3","_nodeVersion":"24.10.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-lMUUFlrzKSTeJ4YBpDB+YqO638IhAnaRFnCU91W1q2UbP04b/qbF2qd3Ilk0zdq7hx4NPNW0RnmTh6e7RslBow==","shasum":"304999e51f618e60f8ea828dbbf52cb3fcccf8bc","tarball":"https://registry.npmjs.org/telegram-mcp-connect/-/telegram-mcp-connect-0.1.3.tgz","fileCount":4,"unpackedSize":46696,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBT/3gOI9VvVyqfHwGGjyVWyXdm8RRiNOluEsxPQRqDKAiAMVotsXxTIYHMNA62vHUM57XUttdhhaN52M2MKd4L6+Q=="}]},"_npmUser":{"name":"sharathxct","email":"sharathxct@gmail.com"},"directories":{},"maintainers":[{"name":"sharathxct","email":"sharathxct@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telegram-mcp-connect_0.1.3_1785374982065_0.8935360424748584"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-30T00:46:38.416Z","modified":"2026-07-30T01:29:42.368Z","0.1.0":"2026-07-30T00:46:38.610Z","0.1.1":"2026-07-30T01:07:47.293Z","0.1.2":"2026-07-30T01:25:24.119Z","0.1.3":"2026-07-30T01:29:42.236Z"},"bugs":{"url":"https://github.com/sharathxct/telegram-mcp-connect/issues"},"license":"MIT","homepage":"https://github.com/sharathxct/telegram-mcp-connect#readme","keywords":["telegram","telegram-mcp","mcp","mcp-server","modelcontextprotocol","model-context-protocol","claude","claude-code","codex","cursor","windsurf","telegram-client","mtproto","ai-agent","chat"],"repository":{"type":"git","url":"git+https://github.com/sharathxct/telegram-mcp-connect.git"},"description":"Telegram MCP server that runs locally. Connect Telegram to Claude Code, Codex, Cursor and other MCP clients to read chats, search messages and summarise conversations. Your session stays on your machine.","maintainers":[{"name":"sharathxct","email":"sharathxct@gmail.com"}],"readme":"# telegram-mcp-connect\n\nConnect Telegram to Claude Code, Codex, Cursor and any other MCP client. It runs as a Telegram MCP server on your own machine and gives your assistant read access to your Telegram account, so you can ask about your chats in plain language.\n\n```\n\"summarise the last few messages in Acme\"\n\"what did I miss in my unread chats today?\"\n\"search my telegram for that link someone sent about that restaurant\"\n```\n\nYour Telegram session is stored in one file on your laptop. Nothing is uploaded and there is no server in the middle.\n\n## Install\n\nYou need [Node.js](https://nodejs.org) 18 or newer. If you have `npm`, you already have it.\n\n```bash\nnpx telegram-mcp-connect setup\n```\n\nThe setup wizard walks through three things:\n\n1. **Creating a Telegram app.** It opens [my.telegram.org/apps](https://my.telegram.org/apps) for you and tells you which two values to copy back.\n2. **Signing in.** Phone number, then a login code. The code arrives inside the Telegram app, not by SMS.\n3. **Connecting your editors.** It detects Claude Code, Codex, Cursor, VS Code, Zed, Windsurf, Gemini CLI and others, then writes the config for whichever ones you pick.\n\nRestart your editor and ask it something about your Telegram.\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `tg_get_me` | Shows which account is connected |\n| `tg_list_chats` | Lists your chats newest first, with unread counts |\n| `tg_read_chat` | Reads recent messages from one chat |\n| `tg_search` | Searches your messages globally or inside one chat |\n\n### Naming a chat\n\nYou can refer to a chat the way you would say it out loud. All of these work:\n\n```\n\"Acme <> Contoso\"    exact title\n\"acme contoso\"       punctuation and case are ignored\n@some_channel        username\n-1001234567890       numeric id from tg_list_chats\n```\n\nIf a name matches more than one chat, the server says which ones so you can pick.\n\n### Reading further back\n\n`tg_read_chat` returns 30 messages by default and 100 at most. To page backwards, pass `beforeId` set to the lowest message id you have already seen.\n\n## Sending messages\n\nOff by default. The setup wizard asks whether you want it, and you can also turn it on for one editor at a time:\n\n```bash\n# Claude Code can send, Cursor stays read only\nnpx add-mcp telegram-mcp-connect@latest -g -a claude-code --args --allow-write\nnpx add-mcp telegram-mcp-connect@latest -g -a cursor\n```\n\nThat adds `tg_send_message` and `tg_mark_read`.\n\n## Where your credentials live\n\nEverything sits in `~/.telegram-mcp-connect/config.json` with `0600` permissions, in a `0700` directory. That file is the only copy. It is deliberately kept out of your editors' config files, which are plain text and often end up inside a git repo.\n\nTwo things worth knowing before you run this:\n\n**Telegram has no read only credential.** The session that reads your chats can also send messages and delete the account. This server only exposes read tools by default, but the session it holds is not itself restricted. Run it on a computer you control.\n\n**Messages from group chats are untrusted text.** If your assistant reads a message that says \"ignore your previous instructions\", that is a prompt injection attempt. Keeping sending disabled limits what such a message can do.\n\nTo revoke access, either run the command below or open Telegram and go to Settings > Devices.\n\n```bash\nnpx telegram-mcp-connect logout\n```\n\nThis revokes the session on Telegram's side and deletes the local file.\n\n## Troubleshooting\n\n```bash\nnpx telegram-mcp-connect doctor\n```\n\nIt checks your credentials, file permissions and connection, prints the account you are signed in as, and lists which editors have the server registered.\n\n**The editor cannot see the server.** Restart it. Most MCP clients only read their config at startup.\n\n**\"Not signed in to Telegram\".** Your session was revoked, usually from Settings > Devices. Run `setup` again.\n\n**Login code never arrives.** Check the Telegram app itself rather than your SMS inbox. Telegram sends it as a message from the account named \"Telegram\".\n\n## Configuration\n\nYou do not normally need these. `setup` writes the config file for you. They exist for containers and CI, and they override the config file when set.\n\n| Variable | Purpose |\n| --- | --- |\n| `TG_API_ID`, `TG_API_HASH` | Telegram app credentials |\n| `TG_SESSION` | Session string |\n| `TG_ALLOW_WRITE` | Set to `1` to enable the send tools |\n| `TG_MCP_HOME` | Config directory, defaults to `~/.telegram-mcp-connect` |\n| `TG_MCP_LOG_LEVEL` | `error`, `warn`, `info` or `debug`, written to stderr |\n| `TG_MCP_CONNECT_TIMEOUT_MS` | How long to wait for Telegram before giving up, defaults to 20000 |\n\n`NO_COLOR` is respected for all CLI output.\n\n## Development\n\nBuilt with [Bun](https://bun.com) and shipped as plain Node.\n\n```bash\nbun install\nbun test\nbun run dev setup     # run the CLI from source\nbun run build         # produce dist/cli.js\n```\n\nAnything under `src/` and `bin/` has to run on Node 18, since users install through `npx`. Bun only APIs like `Bun.file` and `import.meta.dir` will build fine and then crash for everyone.\n","readmeFilename":"README.md"}