mcp server

FlowCastle

Build, edit, and deploy Telegram bots on FlowCastle's hosted visual flow platform.

Description as published by the maintainer. Source

• version 1.0.0
• active

active — Most recent push to the repository was 2026-07-25.

What this server can do

28 functions, named and described by the server itself. Parameter names are shown because they say more about what a function does than its name usually does.

apply_actions(flowId, actions, applicationId, conversationId)

Validate and apply a batch of flow-builder actions — the single write path for editing flows, blocks, variables, broadcasts, sequences, and folders. Call this directly; a separate validate_actions call beforehand is unnecessary. Broadcasts have no dedicated tool and are managed here: create_broadcast makes a DRAFT (it owns its flow via data.flowId — add the message blocks in the same batch, no separate create_flow), optionally with create_recurrence_schedule + attach_recurrence_to_broadcast for recurring; a later update_broadcast with status SCHEDULED (and scheduledAt for one-shots) is what actually schedules/sends it. The full recipe is in get_action_schema under `broadcasts`. DESTRUCTIVE: the batch may include delete_block, delete_link, delete_flow, and delete_variable. Confirm with the user before applying deletions. IRREVERSIBLE SIDE EFFECTS: run_operation starts a real operation run, which may send broadcasts to real contacts and write application variables. It cannot be undone or recalled, is not idempotent, and is available only through this tool — confirm with the user before applying a batch containing one, and never blindly retry a timed-out call that did. Validation always runs first and an invalid batch applies nothing. Execution is NOT atomic, however: if an action fails mid-batch, the actions before it stay applied and execution stops — re-read state with get_flow_context before retrying rather than blindly resending the batch. Not idempotent — resending a batch of create_* actions creates duplicates. Read get_action_schema for the action contract and get_design_guidelines before any structural edit. Returns { success, changes, errors, warnings, actionId } plus an idRemap mapping placeholder ids to the real ids that were created. Required: actions.

create_application(name, skipDefaultFlows, preferredLanguage)

Create a new application (workspace) owned by the caller. Requires a personal API key (usr_...) — application-scoped keys cannot create applications. Seeds default flows unless skipDefaultFlows is true. Creates persistent state and is NOT idempotent: calling it twice creates two applications. Returns the new application id, which you then pass as applicationId to the other tools.

create_contact(botId, email, phone, status, lastName, username, firstName, variables, platformId, applicationId)

Create a contact manually — for imports or externally-sourced audiences; contacts who message a bot are created automatically. Requires the manage_broadcasts permission. platformId must be unique within the bot (duplicate fails with 409); botId may be omitted only when the application has exactly one bot. The variables map takes variable NAMES (or full folder paths when a name is ambiguous) — not ids — and unknown names fail with 422. NOT idempotent: retrying a success creates nothing new only because the duplicate platformId is rejected. Required: platformId.

get_action_schema

Return the action-authoring contract: every supported action kind with its required fields, the placeholder ids for referencing entities created earlier in the same batch, the `{{var|...}}` / `{{sysvar|...}}` / `{{out|...}}` reference syntax, and the creatable block types. Read-only, takes no arguments, and needs no API key. Read this before drafting any apply_actions batch — it is the schema those actions are validated against.

get_application_context(applicationId)

Return the full application-level automation context in one read-only call: every flow (with folders), connected bots, variables, sequences, and operations. This is the broad orientation call — prefer get_workspace_summary when you only need names and counts, since this response grows with workspace size. Operation graphs are hidden flows and appear only in the operations list, never in flows.

get_block_details(flowId, blockId, applicationId)

Return the complete contents of one block: block data, action configs, HTTP request bodies, custom-code files, triggers, menu payloads, and media paths. Read-only. This is the heaviest read in the API — call get_flow_context first to find the block you need rather than walking a flow block by block. Always read a block before updating it, since update_block replaces the fields you send. Required: flowId, blockId.

get_broadcast_analytics(endDate, startDate, broadcastId, applicationId)

Return engagement analytics for a broadcast: delivery breakdown by status plus per-message-block sent and clicked counts for its flow, over an optional date window. Read-only. Sent counts reflect messages attempted, not confirmed deliveries. Required: broadcastId.

get_broadcast_details(broadcastId, applicationId)

Return full details for a single broadcast: status, schedule, recurrence rule, linked flow, and delivery breakdown by status. Read-only. Call list_broadcasts first to find the broadcastId. For per-message-block engagement stats use get_broadcast_analytics instead. Required: broadcastId.

get_contact(contactId, applicationId)

Return one contact's full profile plus every contact-variable value stored for them. Read-only. Values may hold personal data; variables of type SECRET are always redacted. Call list_contacts first to find the contactId. Required: contactId.

get_design_guidelines

Return the flow-design rules that validation does NOT enforce: when to split a branch into its own flow, how navigation and menus must be wired, and worked examples. Read-only, takes no arguments, and needs no API key. Read this before any structural edit (new blocks, new branches, new flows) — a batch can pass validate_actions and still be badly structured, and these rules are what catch that.

get_flow_context(flowId, applicationId)

Return one flow's graph topology: its blocks, how they link, and a short summary per block. Read-only. Deliberately omits block data and action configs to stay cheap — once you know which block matters, call get_block_details for its full contents. This is the normal first step before editing an existing flow. Required: flowId.

get_flow_example(id, includeSchemaExample)

Return one reusable flow example by id, optionally with a complete action batch you can adapt and pass to apply_actions. Read-only, needs no API key. Call search_flow_examples first to find the id. Required: id.

get_module_catalog(applicationId)

Return a compact index of both installed and available marketplace modules, with each module's key, versions, description, actions, and triggers. Read-only. Start here when you need a capability the core action kinds do not cover; then call get_module_details for the exact input fields of one module, and install_module to add it. Returns a summary only — action input fields and setup requirements come from get_module_details.

get_module_details(moduleKey, applicationId, moduleVersion)

Return everything needed to use one module: action input fields and their types, trigger configuration, manual setup fields (credentials an operator must fill in the dashboard), and references to already-installed actions. Read-only. Call get_module_catalog first to obtain moduleKey, and call this again after install_module to read the installed action references you need when drafting actions. An unknown moduleKey does not raise — the response carries an `error` string plus `availableModules` listing valid keys and versions. Required: moduleKey.

get_variable_context(limit, query, scope, applicationId, includeValues)

Search variable definitions by scope and keyword. Read-only. Returns { variables, total, returned, truncated } — compare returned against total to detect a cut-off result set and re-call with a higher limit. Values are withheld unless includeValues is true; variables marked secret stay redacted either way. Use the returned ids in `{{var|<id>}}` references.

get_workspace_summary(flowId, applicationId)

Return a compact application, flow, sequence, operation, and bot summary — the cheapest way to orient in a workspace. Read-only, no side effects. Deliberately omits variables and full flow graphs: use get_variable_context for variables, get_flow_context for a flow's topology, and get_application_context when you need flows, bots, and variables together.

install_module(moduleKey, applicationId, moduleVersion)

Install an exact marketplace module version into an application and create any missing installed-template actions. Requires the manage_automation permission. Call get_module_catalog first to select the module and version, then get_module_details after installation to inspect setup requirements and installed action references. Safe to re-run: installing a version that is already installed only fills in missing template actions rather than duplicating them. Modules with manual setup fields still need an operator to enter credentials in the dashboard before their actions will run. Required: moduleKey, moduleVersion.

list_applications

List the applications this API key can access, with the caller role and the permissions it grants. Start here when using a personal API key (usr_...): every other tool needs an explicit applicationId, which this tool supplies. Read-only, takes no arguments. Returns an array of { id, name, role, permissions }; an empty array means the key is valid but belongs to no application yet.

list_broadcasts(page, botId, limit, status, isRecurring, applicationId)

List broadcasts in the application with status, schedule, and delivery counts. Read-only. Filters combine as AND. Note that delivery counts report messages attempted, not confirmed deliveries. Use get_broadcast_details for one broadcast's full breakdown. To CREATE or SEND a broadcast use apply_actions: create_broadcast makes a draft, update_broadcast (status SCHEDULED) schedules/sends it — see get_action_schema under `broadcasts`.

list_contacts(page, botId, limit, search, status, isActive, applicationId)

List and search contacts in the application, paginated, newest first. Read-only. Filters combine as AND; search matches name, username, email, phone, and platformId. Returns compact contact summaries without variable values — use get_contact for one contact's variables. Remember platformId is unique only per bot, so the same person talking to two bots appears as two contacts.

list_watched_groups(botId, applicationId)

List the group/channel chats a telegram_mtproto userbot monitors. Read-only. The watched list is the single source of truth for which chats the userbot processes: messages from unlisted group/channel chats are dropped (fail closed) and their contacts never materialize; DMs always pass. botId may be omitted when the application has exactly one userbot.

search_flow_examples(tags, limit, query)

Search the library of reusable flow examples covering common business cases (lead capture, onboarding, payments, reminders). Read-only, needs no API key. Returns compact matches — id, title, summary, tags — with no flow body; pass an id to get_flow_example for the full example. Calling it with no arguments returns the top examples, and a query matching nothing returns an empty list rather than an error.

send_message(text, botId, media, contactId, platformId, applicationId)

Send a message to ONE contact right now, outside any flow. For reaching many contacts use a broadcast instead. Target the contact with contactId (globally unique — preferred), or with platformId (the platform-side id, e.g. the Telegram user id). platformId is NOT globally unique: it is unique only per bot, so the same Telegram user talking to two of your bots is two contacts sharing one platformId. Pass botId alongside it whenever the application has more than one bot; without botId the call succeeds only if exactly one contact in the application matches, and otherwise fails listing the candidate bots. `{{var|name}}` placeholders in the text resolve against that contact's variable context. Requires the manage_broadcasts permission. Media: pass up to 10 attachments as publicly reachable http(s) URLs; the text becomes the caption (max 1024 characters) and may be empty. Several attachments send as one album. The kind is inferred from the URL's file extension — override with type when the URL has none. Not supported for SDK bots. Delivery is asynchronous: a successful response means the bot accepted the send, not that the platform delivered it (a broken media URL surfaces in the flow logs, not here). Unsubscribed contacts are rejected. NOT idempotent and not reversible — each call sends another message to a real person, and a sent message cannot be recalled. Confirm the recipient and text with the user before calling, and never retry a timed-out call blindly.

set_watched_groups(botId, groups, applicationId)

Replace a telegram_mtproto userbot's watched-groups list — the chats it monitors. Requires the manage_settings permission. SET semantics: send the COMPLETE desired list every time (call list_watched_groups first and include existing entries you want to keep — omitting one removes it). Each entry needs a chatId (e.g. "-100…", for chats the account has joined) or a public username/t.me link; mode "joined" (default) processes a chat the account is in, "public_peek" (max 10, needs a username) polls a public chat without joining. The running userbot picks the change up within a few minutes, no restart. An empty list means "watch every joined chat" — NOT "watch nothing". Required: groups.

sync_dialog_contacts(botId, kinds, limit, applicationId)

Import a telegram_mtproto userbot's existing chats as contacts — DM partners, groups, and channels — so everything the account already talks to becomes a valid send_message target without waiting for each chat to message first. Requires the manage_broadcasts permission. Reads the account's dialog list live (the userbot must be connected; large accounts can take up to a minute) and creates missing contacts; existing contacts are untouched, so the call is idempotent. Pass kinds to narrow the import (e.g. ["group","channel"] to leave personal DMs out). Does NOT change the watched-groups list. botId may be omitted when the application has exactly one userbot.

update_application(name, isActive, applicationId, defaultLanguage, incomingMessageFlowId, incomingMessageBehavior)

Update application-level settings (name, active state, default language, incoming-message behavior). Requires the manage_settings permission in that application. Only the fields you pass are changed; omitted fields keep their current value, so the call is idempotent. Returns the updated application.

update_contact(email, phone, status, lastName, username, contactId, firstName, variables, applicationId)

Update a contact's profile fields and/or contact-variable values. Requires the manage_broadcasts permission. Only the fields you pass are changed — omitted fields keep their current value — so the call is idempotent. The variables map takes variable NAMES (or full folder paths when a name is ambiguous), not ids; an unknown name fails with 422 before anything is written. Variable writes propagate to the live bot immediately (the runtime's cached values are invalidated). Setting status to "unsubscribed" stops broadcasts and sequences for the contact. Required: contactId.

validate_actions(flowId, actions, applicationId, conversationId)

Dry-run validation of a proposed batch of flow-builder actions. Mutates nothing and is safe to repeat. OPTIONAL: apply_actions runs this exact validation itself and applies nothing when invalid, so calling validate_actions first is redundant — use it only to check a draft you do not intend to apply yet. Returns the same errors and warnings apply_actions would report. Note that passing validation does not mean the design is sound; structural rules live in get_design_guidelines. Required: actions.

Last successful function declaration observed on 2026-08-13. Source: https://api.flowcastle.ai/api/mcp. We list what the server declared; we do not call any of these functions.

Endpoint status observed on 2026-08-13. Source: https://api.flowcastle.ai/api/mcp.

Signals

These are separate measurements of different things. They are deliberately not combined into one score, because a popularity number that mixes website traffic with saves and stars cannot be checked or acted on.

Where to get it

• Repository — https://github.com/FlowCastle/telegram-bot-templates
• Website — https://flowcastle.ai
• Remote endpoint (streamable-http) — https://api.flowcastle.ai/api/mcp

Related, by what their authors tagged them

• io.github.GeiserX/telegram-archive-mcp — last commit 2026-08-01, shares telegram, telegram-bot
  MCP server for Telegram Archive — search messages, browse chats, and access history
• Chamade — last commit 2026-06-04, shares telegram
  Voice and chat for AI agents — Discord, Teams, Meet, Slack, Zoom, Telegram, WhatsApp, NC Talk, SIP
• Notify MCP Server — last commit 2026-03-26, shares telegram
  MCP Server for notify to Weixin, Telegram, Bark, Lark, Feishu, DingTalk
• io.github.fieldcure/outbox — last commit 2026-05-25, shares telegram
  Multi-channel messaging MCP server for Slack, Telegram, Email, KakaoTalk, and Discord.
• Biel.ai — last commit 2026-07-22, shares chatbot
  Query your product docs from AI tools. Source-cited answers from your indexed documentation.
• dev.safeprompt/mcp — last commit 2026-08-03, shares chatbot
  Detect prompt injection, jailbreaks, and code injection in untrusted text before it reaches an LLM.
• io.github.0xSoftBoi/suwappu — last commit 2026-08-06, shares telegram-bot
  Cross-chain DEX for AI agents. Swap tokens across 7+ chains.
• io.github.AceDataCloud/mcp-aichat — last commit 2026-08-04, shares chatbot
  MCP server for AI dialogue using various LLM models via AceDataCloud
• io.github.Adgentek/adsmcp — last commit 2026-05-28, shares chatbot
  MCP-native ad server. Monetize AI chatbots and agents with conversational ads.
• ARGUS-3 MCP Server — last commit 2026-08-06, shares telegram-bot
  ARGUS-3 stdio MCP with WARDEN firewall: argus_ask, argus_status, argus_capabilities.

These share tags the maintainers applied themselves, such as telegram, telegram-bot, chatbot. Common tags like "mcp" or "ai" are ignored for this: agreeing with six hundred other projects is not a similarity.

This is not a recommendation and not a test result. It is a map of what the authors said their work is about.

How the author describes it

Topics the maintainer set on GitHub: ai-agents, bot-builder, bot-development, chatbot, mcp, mcp-server, model-context-protocol, no-code, telegram, telegram-bot, telegram-bot-templates, workflow-automation.