{"id":28477455,"url":"https://github.com/tacticlaunch/mcp-telegram","last_synced_at":"2026-02-16T17:34:11.484Z","repository":{"id":285421132,"uuid":"957683265","full_name":"tacticlaunch/mcp-telegram","owner":"tacticlaunch","description":"A TypeScript implementation of an MCP (Model Context Protocol) server for working with Telegram through MTProto","archived":false,"fork":false,"pushed_at":"2025-03-31T16:14:05.000Z","size":71,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-22T19:24:28.398Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tacticlaunch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-30T23:53:15.000Z","updated_at":"2025-04-02T11:42:28.000Z","dependencies_parsed_at":"2025-03-31T17:38:14.117Z","dependency_job_id":null,"html_url":"https://github.com/tacticlaunch/mcp-telegram","commit_stats":null,"previous_names":["tacticlaunch/mcp-telegram"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tacticlaunch/mcp-telegram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tacticlaunch%2Fmcp-telegram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tacticlaunch%2Fmcp-telegram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tacticlaunch%2Fmcp-telegram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tacticlaunch%2Fmcp-telegram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tacticlaunch","download_url":"https://codeload.github.com/tacticlaunch/mcp-telegram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tacticlaunch%2Fmcp-telegram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29513994,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T09:05:14.864Z","status":"ssl_error","status_checked_at":"2026-02-16T08:55:59.364Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-07T16:36:07.369Z","updated_at":"2026-02-16T17:34:11.476Z","avatar_url":"https://github.com/tacticlaunch.png","language":"TypeScript","readme":"# MCP Telegram\n\nA TypeScript implementation of an MCP (Model Context Protocol) server for working with Telegram through MTProto, built using FastMCP.\n\n## Overview\n\nThis project provides a set of tools for interacting with Telegram through the MTProto protocol, making them available via an MCP server for use with AI models like Claude.\n\n## Installation\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n## Usage\n\n### CLI Commands\n\nThe application provides the following CLI commands:\n\n```bash\n# Sign in to Telegram\nnpm run sign-in\n# or\nnpx mcp-telegram sign-in\n\n# Start the MCP server\nnpm run mcp\n# or \nnpx mcp-telegram mcp [options]\n\n# Logout from Telegram\nnpm run logout\n# or\nnpx mcp-telegram logout\n```\n\nCLI Options for the `mcp` command:\n- `-t, --transport \u003ctype\u003e`: Transport type (stdio, sse), defaults to 'stdio'\n- `-p, --port \u003cnumber\u003e`: Port for HTTP/SSE transport, defaults to 3000\n- `-e, --endpoint \u003cpath\u003e`: Endpoint for SSE transport, defaults to 'mcp'\n\n### Starting the MCP Server\n\nStart the MCP server with stdio transport (default, used by Cursor AI):\n```bash\nnpm run start\n# or\nnpm run mcp\n```\n\nYou can also run the server programmatically:\n\n```typescript\nimport server, { startServer } from 'mcp-telegram';\n\n// Start the server with the configuration\nstartServer(server);\n```\n\n### Environment Variables\n\nThe application uses the following environment variables:\n\n- `TELEGRAM_API_ID`: Your Telegram API ID\n- `TELEGRAM_API_HASH`: Your Telegram API Hash\n- `TRANSPORT_TYPE`: Transport type ('stdio', 'http', or 'sse'), defaults to 'stdio'\n- `PORT`: Port for HTTP or SSE transports, defaults to 3000\n- `ENDPOINT`: Endpoint for SSE transport, defaults to 'mcp'\n- `LOG_LEVEL`: Logging level, defaults to 'info'\n\nThese can be set in a `.env` file in the project root.\n\n## Development\n\nDevelopment requires Node.js version 18 or higher.\n\n```bash\n# Run in development mode\nnpm run dev\n\n# Lint the code\nnpm run lint\n\n# Run tests\nnpm run test\n```\n\n## FastMCP Integration\n\nThe server is implemented using FastMCP, which provides a modern TypeScript implementation of the Model Context Protocol. It supports stdio and SSE transports, making it compatible with different client integration approaches.\n\n### Server Transports\n\n- **stdio**: Default transport, useful for direct integration with tools like Cursor AI\n- **sse**: Server-Sent Events transport for real-time communication\n\n## Available Tools\n\n### listDialogs\n\nList available dialogs, chats and channels.\n\nParameters:\n- `unread`: Boolean, show only unread dialogs (default: false)\n- `archived`: Boolean, include archived dialogs (default: false)\n- `ignorePinned`: Boolean, ignore pinned dialogs (default: false)\n\n### listMessages\n\nList messages in a given dialog, chat or channel.\n\nParameters:\n- `dialogId`: String, ID of the dialog to list messages from\n- `unread`: Boolean, show only unread messages (default: false)\n- `limit`: Number, maximum number of messages to retrieve (default: 100)\n\n## Project Structure\n\n```\nsrc/\n├── config.ts               # Application configuration\n├── index.ts                # Main server implementation\n├── mcp.ts                  # CLI entry point\n├── tools/                  # Tool implementations\n│   ├── index.ts            # Tools export\n│   └── telegramTools.ts    # Telegram tools\n├── lib/           # Core Telegram functionality\n│   ├── index.ts            # Module exports\n│   ├── telegram.ts         # Telegram client functionality\n└── utils/                  # Utilities\n    ├── errorHandler.ts     # Error handling utilities\n    └── logger.ts           # Logging utility\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.","funding_links":[],"categories":["🌐 Web Development"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftacticlaunch%2Fmcp-telegram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftacticlaunch%2Fmcp-telegram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftacticlaunch%2Fmcp-telegram/lists"}