Dynamic Telegram Bot API MCP Server

Dynamic Telegram Bot API MCP Server

A production-oriented Model Context Protocol server that exposes the complete Telegram Bot API through five stable tools. It parses Telegram's official documentation into a normalized local catalog, so new Bot API methods and objects become available after a schema refresh without source-code changes.

The checked-in catalog targets the Telegram Bot API version recorded in data/telegram-bot-api.json and contains every method and type published in the official documentation.

MCP tools

There is deliberately no generated tool per Bot API method. The catalog and generic call tool are the API surface.

Requirements and installation

• Node.js 20.18.1 or later
• A bot token from @BotFather for API calls (catalog tools work without one)

Install from npm

Run the published npm package directly with npx—no repository checkout or build is required:

Create a .env in each project or repository with that project's bot token:

TELEGRAM_BOT_TOKEN=YOUR_PROJECT_BOT_TOKEN
TELEGRAM_METHOD_ALLOWLIST=get*,sendMessage,sendPhoto

Configure the MCP server once, without a shared token or hard-coded working directory:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "dynamic-telegram-bot-api-mcp"]
    }
  }
}

For Codex, the equivalent ~/.codex/config.toml entry is:

[mcp_servers.telegram]
command = "npx"
args = ["-y", "dynamic-telegram-bot-api-mcp"]

Alternatively, install it globally with npm install -g dynamic-telegram-bot-api-mcp and use "command": "telegram-bot-api-mcp" in the configuration above, omitting args.

Registry name: io.github.patricktobias86/dynamic-telegram-bot-api-mcp.

Install from GitHub

Clone and build the GitHub repository:

git clone https://github.com/PrimeUpYourLife/dynamic-telegram-bot-api-mcp.git
cd dynamic-telegram-bot-api-mcp
npm ci
npm run build

Then configure an MCP client to start the built stdio server. Use an absolute repository path:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/absolute/path/dynamic-telegram-bot-api-mcp/dist/index.js"]
    }
  }
}

Before each telegram_call_method request, the server asks clients that support MCP roots for their current workspace root and loads <workspace-root>/.env. A project-local token overrides a shared process token, so one persistent MCP server can safely switch between repositories without restarting. Configuration and clients are cached only while the relevant connection settings remain unchanged; edits to .env are picked up on the next call.

The workspace must expose exactly one local directory root. Multiple roots return PROJECT_ROOT_AMBIGUOUS instead of guessing which bot to use. If the client does not support MCP roots or returns no roots, the server falls back to its startup environment and current working directory for backward compatibility.

For local development from the GitHub checkout, run npm run dev. Never commit a token.

Tool examples

Search:

{ "search": "send photo", "limit": 10 }

Inspect a method or object:

{ "method": "sendPhoto" }

{ "type": "InlineKeyboardMarkup" }

Call any method:

{
  "method": "sendMessage",
  "parameters": {
    "chat_id": 123456789,
    "text": "Hello"
  }
}

Method lookup is case-insensitive. Parameter names follow Telegram's official snake_case contract.

File uploads

File IDs and HTTP URLs pass through unchanged. A local path may be supplied for an InputFile-capable field:

{
  "method": "sendPhoto",
  "parameters": {
    "chat_id": 123456789,
    "photo": "./uploads/photo.jpg"
  }
}

For an explicit local upload descriptor or in-memory binary payload:

{ "path": "./uploads/photo.jpg", "filename": "photo.jpg", "contentType": "image/jpeg" }

{ "base64": "iVBORw0KGgo...", "filename": "photo.png", "contentType": "image/png" }

Descriptors also work inside nested media objects. For fields documented with attach://, local paths are replaced with attachment references and the request is sent as multipart/form-data. Upload bytes are normalized to an ArrayBuffer-backed copy before constructing each multipart file. Paths are resolved through realpath, restricted to configured roots, required to be regular files, and size-limited.

Configuration

Validation and error behavior

The gateway validates method existence, unknown and required parameters, primitive types, arrays, nested Telegram objects, union variants, and cataloged enum values before sending a request. Telegram's prose contains some conditional rules that cannot be represented mechanically; Telegram remains authoritative for those constraints.

Tool failures are marked as MCP errors and return structured content:

{
  "ok": false,
  "error": "VALIDATION_ERROR",
  "description": "text: required parameter is missing",
  "parameters": {
    "issues": [{ "path": "text", "message": "required parameter is missing" }]
  }
}

Telegram error codes, descriptions, and response parameters such as retry_after and migrate_to_chat_id are preserved. HTTP error bodies and stack traces are not exposed.

Security model

• The bot token is read only from the startup environment or the active MCP workspace root's .env. It is never included in tool output or audit fields, and defensive redaction is applied to Telegram descriptions.
• The server refuses ambiguous multi-root workspaces and non-local roots instead of risking selection of the wrong bot.
• Audit records are JSON lines on stderr and contain method name, parameter names, timing, retry count, and status—not parameter values.
• Destructive method families (for example delete*, ban*, revoke*, refund*, and stop*) require confirm: true.
• TELEGRAM_METHOD_ALLOWLIST can limit methods available to the call tool. Prefer a narrow production allowlist.
• Local files are confined to TELEGRAM_LOCAL_FILE_ROOTS; symlink escapes and non-regular files are rejected.
• Rate limiting is process-local. Use an external distributed limiter when running multiple replicas.

Retries can duplicate non-idempotent operations if the network fails after Telegram accepts a request. Set TELEGRAM_REQUEST_RETRIES=0 for workloads where that risk outweighs availability.

Schema updates

At startup, the server refreshes catalogs older than 24 hours. If an existing catalog is available and Telegram cannot be reached or the documentation shape fails integrity checks, startup continues with the last valid catalog. A first startup without any valid catalog fails closed.

Refresh manually with the MCP tool or:

npm run refresh-schema

The daily GitHub Actions workflow refreshes the catalog, synchronizes the npm package version with Telegram's Bot API version, then checks, tests, builds, and commits any updates. It creates a GitHub release and dispatches the npm publishing workflow when that version has not been published. Publishing a GitHub release also triggers npm publication directly; prereleases use the next npm tag. Writes are atomic, and concurrent in-process refreshes are coalesced.

Development

npm run check
npm test
npm run build

The parser has minimum method/type count guards to prevent a changed or partial documentation page from replacing a good catalog. When Telegram changes the HTML presentation rather than merely adding API entries, update the parser and its fixture test.

License

MIT