telegram-bot-framework-mcp
Indexes and provides access to the source code and documentation of the TelegramBotBase package, which is the underlying library for the TelegramBotFramework.
Provides comprehensive tools to read and understand the real source, documentation, and API changes of the TelegramBotFramework, enabling AI assistants to assist in developing Telegram bots.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@telegram-bot-framework-mcp How do I persist user sessions across restarts? Check the state machine classes."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
telegram-bot-framework-mcp
Give your AI assistant the real source, docs and a curated how-to guide for the TelegramBotBase .NET framework.
Quick start · Tools · Examples · Self-hosting · Upgrading · CI
An MCP server that lets an AI assistant answer questions about
MajMcCloud/TelegramBotFramework (NuGet: TelegramBotBase) from the actual
source code, not from memory. It ships as a Docker image with the framework source baked in, pinned to
8.0.0-preview.2 (development branch, commit 6780abf), together with a curated how-to guide.
Feature | |
Ask in plain English |
|
Exact answers | read real signatures, doc comments and example bots straight from the pinned source |
Pitfall finder | describe a symptom ("button spins forever") and get the known cause and fix |
Upgrade helper | public API diff between any two tags or commits |
Use it your way | free public endpoint, local Docker (stdio), or your own VPS |
8.0.0-preview.2 is apreview; its API can still change before 8.0.0. The builder in this version has an extra
request dispatcher stage that does not exist in 7.x, so code from the guide will not compile against 7.2.0.
To serve 7.2.0 instead, build with --build-arg TGBOTBASE_REF=13fff09c2736e4616f1d3c5dffe40401b92c81b0 --build-arg TGBOTBASE_NUGET_VERSION=7.2.0 and expect the guide's dispatcher parts to be wrong.
Quick start
Pick one way to connect. Both give the assistant the same tools.
Option | Best for | Command |
Hosted (HTTP) | zero setup |
|
Local (stdio) | reliability, offline |
|
Keep the-i flag in the local command. Without it the container's stdin closes and the connection fails immediately.
The public instance is a free, read-only, best-effort service: rate limited, no uptime guarantee, no token needed.
If the server owner enabled a token, add--header "Authorization: Bearer <token>".
For reliability, run the local image or host your own.
Use the URL above (plus the Authorization header if a token is enabled), or this stdio config:
{ "mcpServers": { "tgbotbase": { "command": "docker",
"args": ["run", "-i", "--rm", "severnbli/telegram-bot-framework-mcp:8.0.0-preview.2"] } } }Check it works: run /mcp in Claude Code, or ask "What framework version does tgbotbase serve?"
The answer should mention 8.0.0-preview.2 and commit 6780abf.
Pin the image tag (:8.0.0-preview.2) in your client config. Prereleases never get the latest tag.
Related MCP server: Atlas Docs MCP Server
Tools
The server also sends usage instructions to the client, so assistants start with ask for any how-to question.
Tool | Use it to |
| Start here. One call searches the guide, pitfalls, types and README and says what to read next |
| Read the curated guide: decision tables (message loop / dispatcher / serializer), patterns, ship checklist. |
| Describe a problem or error name and get the known cause and fix |
| See the TelegramBotBase version, commit and dependencies (e.g. |
| Find C# types by name; see doc comment, base types and public members (typos get "did you mean") |
| Everything deriving from or implementing a type ( |
| Case-insensitive substring search of the source ( |
| Read any file (optionally a line range) or list files under a path |
| List example and test-bot source files |
| Browse and read the framework README (Quick start, ButtonGrid, State Machines, ...) |
| Public API diff between two tags/commits, for example before an upgrade |
Resources: tgbotbase://readme (the framework README) and tgbotbase://guide (the full guide).
The symbol index is built with regular expressions, not a C# compiler. It is good for finding types and
comparing public APIs, but can miss unusual declarations, andget_changes may list a few false positives (for example
a word inside a comment reported as a type). For exact behavior, read the file with get_file.
Example prompts
"Using tgbotbase, write a form with a paged
ButtonGrid. Check the realButtonGridsource for the API.""Which controls exist and how do they differ? Use
find_subclassesonControlBase.""How do I persist user sessions across restarts? Look at the state machine classes."
"How do I show a calendar and read the chosen date?" (uses
ask)"My button spins forever. Why?" (uses
get_gotchas)"Which message loop and request dispatcher should I use for a bot with broadcasts?" (uses the guide's decision tables)
"What changed in the public API between v7.1.0 and the current version?"
tell the assistant toverify against the source (get_symbol, get_file) instead of answering from memory,
and give it your bot's framework version so it can compare with framework_version.
Hosting on a VPS
Runs the container on 127.0.0.1:8000 and puts host nginx in front of it with TLS and per-IP rate limiting.
The server is public by default; a bearer token is optional (see below).
Requirements: Docker, nginx and certbot on the VPS; a DNS A record for tbf-mcp.severnbli.dev pointing at it; ports 80 and 443 open.
1. Start the container
cd deploy && cp .env.example .env
docker compose up -dThe compose file runs the container read-only with a 512 MB memory and 1 CPU limit.
the image tag8.0.0-preview.2 exists on Docker Hub only after the first publish from main (see
CI and publishing). Before that, docker compose up fails with "not found".
2. Configure nginx
sudo cp nginx.conf /etc/nginx/sites-available/tgbotbase-mcp
sudo ln -s /etc/nginx/sites-available/tgbotbase-mcp /etc/nginx/sites-enabled/
sudo certbot certonly --nginx -d tbf-mcp.severnbli.dev
sudo nginx -t && sudo systemctl reload nginxon a fresh VPS the certificate does not exist yet, songinx -t fails on the 443 block. Comment that
block out, run certbot, then restore it. http2 on; needs nginx 1.25.1 or newer; on older versions remove it and
write listen 443 ssl http2;.
the config assumes the domain is proxied through Cloudflare (orange cloud). It trustsCF-Connecting-IP
only from Cloudflare's published ranges, so rate limits apply per real visitor. If you are not behind Cloudflare,
delete the set_real_ip_from / real_ip_header lines. Set Cloudflare SSL/TLS mode to Full (strict).
3. Verify
curl -i https://tbf-mcp.severnbli.dev/mcp # public mode: any response from the MCP server except 401/404/502Optional: require a bearer token
A bearer token is a secret string the client sends as Authorization: Bearer <token>. To enable it, edit the copy in
/etc/nginx/sites-available/tgbotbase-mcp:
Generate a token:
openssl rand -hex 32.In the
mapblock changedefault 1;todefault 0;and uncomment the"Bearer ..."line with your token.sudo nginx -t && sudo systemctl reload nginx, then connect clients with--header "Authorization: Bearer <token>". Requests without it get 401.
put the token only in the copy under/etc/nginx, never in the repo file. Do not commit a real token.
Anyone who has it can use the server. Use HTTPS only, since the token travels in a header.
Updating
cd deploy && docker compose pull && docker compose up -dthe port is bound to127.0.0.1 on purpose. Do not change it to 0.0.0.0: that would bypass nginx's rate
limits (and the token, if enabled).
Upgrading the framework version
Build with the new ref (a tag or commit SHA) and version:
docker build \ --build-arg TGBOTBASE_REF=<tag|sha> \ --build-arg TGBOTBASE_NUGET_VERSION=<x.y.z> \ -t tgbotbase-mcp:<x.y.z> .Update the defaults in the
Dockerfileand the pinned version in this README, then merge tomainto publish.Before changing your bot, ask the assistant for
get_changesbetween the old and new ref to see what to adapt.
the repo does not tag NuGet releases (there is nov7.2.0 or v8.0.0-preview.2). Match the NuGet publish date to a commit on
master and pin that commit SHA.
CI and publishing
ci.ymlruns on every pull request: builds the image, runstests/smoke.pyandtests/test_search.py(search quality) inside it, and runstests/check_guide.py, which fails if the guide mentions a source file that no longer exists in the pinned source (so a version bump can't silently leave the guide stale).publish.ymlruns only on a push tomainor a manual dispatch onmain. It re-runs CI, then pushessevernbli/telegram-bot-framework-mcp:<framework version>(read from theDockerfile; plus:latestfor stable, non-prerelease versions) to Docker Hub forlinux/amd64andlinux/arm64.
publishing needs the repository secretsDOCKERHUB_USERNAME and DOCKERHUB_TOKEN. Without them the
publish job fails at login.
MIT licensed · Not affiliated with the TelegramBotBase authors · Built on the Model Context Protocol
Available Tools
17 toolsaskA
Best first call for any how-to question about building a bot with TelegramBotBase. Searches the guide, the known pitfalls, the type index and the README at once, and tells you which tool to call next.
Inputs: question (required). Returns: result
find_subclassesB
Find types that inherit from / implement base (e.g. FormBase, ControlBase, IStateMachine).
Inputs: base (required). Returns: result
framework_versionA
Which framework version this server's source corresponds to (NuGet version, git commit, date).
Inputs: no named parameters. Returns: result
get_changesA
Public API diff of the TelegramBotBase library between two git refs (tags, branches, SHAs): added/removed types and added/removed public members, plus commit list. Only refs present in the clone work.
Inputs: from_ref (required), to_ref, max_items. Returns: result
get_doc_sectionA
Get README section(s) by case-insensitive partial title, e.g. 'ButtonGrid'.
Inputs: title (required). Returns: result
get_fileC
Read a repository file (optionally a line range).
Inputs: path (required), end_line, start_line. Returns: result
get_gotchasA
Known pitfalls as 'symptom -> cause & fix'. Pass words of your problem or error (e.g. 'spins forever', 'CallbackDataTooLongException'), or nothing for all.
Inputs: symptom. Returns: result
get_guide_sectionA
Read guide section(s) by number or partial title, e.g. '3.4', 'Navigation', 'Checklist'.
Inputs: query (required). Returns: result
get_symbolA
Show a type: doc comment, bases, public/protected members and file path. Use get_file for full source.
Inputs: name (required). Returns: result
list_doc_sectionsC
List README sections.
Inputs: no named parameters. Returns: result
list_examplesB
List C# example and test-bot files.
Inputs: no named parameters. Returns: result
list_filesB
List repository files filtered by path prefix and extension.
Inputs: prefix, extension. Returns: result
list_guide_sectionsA
List sections of the curated how-to guide (decision tables, patterns, gotchas, checklist).
Inputs: no named parameters. Returns: result
list_refsA
List tags and branches available for get_changes.
Inputs: no named parameters. Returns: result
list_symbolsB
List C# types (class/interface/enum/struct/record) by name substring and optional kind.
Inputs: kind, query, max_results. Returns: result
search_codeB
Case-insensitive substring search of the source; returns path:line: text.
Inputs: query (required), extension, max_results, path_prefix. Returns: result
search_guideA
Search the how-to guide with a plain-English question or keywords (e.g. 'handle a button click', 'dispatcher'). Returns the best-matching sections, most relevant first, each with the key matching lines. Read a whole section with get_guide_section.
Inputs: query (required), max_results. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target clearly distinct facets (git refs, symbols, files, code search, README, examples, guide, gotchas), so an agent can usually pick correctly. The overlap is mild: `ask` deliberately subsumes `search_guide`, `get_gotchas`, `list_symbols` and README lookup, and `list_doc_sections`/`list_guide_sections` are two similar-looking pairs, but the docs explicitly frame `ask` as an orchestrator so the boundaries are explained.
Names follow a clear verb_noun convention (list_refs, get_symbol, find_subclasses, search_code, get_guide_section) across the whole set. Only two deviations stand out: the noun-only `framework_version` and the verb-only `ask`, which are minor and readable.
17 tools is on the heavy side for what is essentially a read-only repo/docs browser, and several doc-navigation tools (list_doc_sections/get_doc_section, list_guide_sections/get_guide_section, search_guide) could arguably be consolidated. Each still maps to a real facet of the repo, so it is heavy rather than bloated.
The surface covers versioning, API diffs, refs, symbol/subclass lookup, file listing and reading, code search, README, examples, the curated guide and pitfalls, and even an orchestrator entry point — a solid lifecycle for a documentation/reference server. Minor gaps remain: no full-text README search, no example-file search, and no way to enumerate all symbols in one call.
Maintenance
Related MCP Connectors
Search, inspect and inject full source modules (code + AI rules + MCP) pinned to a Git commit.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
A cited wiki of your GitHub repo: search, read pages, find symbols and ask, with line citations.
Search and inspect source-pinned agent skills, plugins and tools through a free public MCP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI models to fetch GitHub repository information, read file contents, and search local documentation.-
- AlicenseAqualityDmaintenanceProvides AI assistants with up-to-date documentation for popular libraries and frameworks, enabling them to generate more accurate code using less common or newly released libraries.536MIT
- FlicenseNot gradedqualityAmaintenanceEnables clients to retrieve real-time framework documentation for any npm package, returning TypeScript types, prose, and code examples with intent-aware formatting, plus version migration guidance, error diagnosis, package comparison, and dependency scanning.-
- AlicenseNot gradedqualityBmaintenanceEnables agents to search pinned robotics code and reusable task findings across frameworks, inspect provenance and requirements, and prepare supported upstream sources via recipes without executing robot code.Apache 2.0