# MessageBird MCP > MessageBird connects your AI client to a global communications API for SMS messaging and contact management. Your agent can send texts instantly, check account balances in real-time, and audit entire contact databases without you opening any web dashboard. It manages everything from sending verification codes to running complex marketing broadcasts. ## Overview - **Category:** communication-messaging - **Price:** Free - **Tags:** omnichannel, sms-gateway, contact-management, messaging-api, customer-engagement, real-time-sync ## Description Listen up. This server connects your AI client directly to MessageBird's global communications API. You don't have to open any web dashboard or mess with complex forms; your agent handles every single message and audit in a natural chat conversation. It’ll manage everything from sending basic verification texts right through to running deep audits on your entire contact database. **Sending Messages & Checking Funds** Your agent can use `send_sms` to send an SMS text to any recipient globally, and you get immediate confirmation of the transaction status. You'll know instantly if the message went out successfully. Before you launch a big campaign, run `get_balance` and your agent pulls the current dollar amount available in your account; this lets you monitor spending on the fly so you don't blow through your budget unexpectedly. **Contact Database Management** Need to know who's in your roster? Use `list_contacts`, and your agent pulls a full list of contacts, complete with their metadata. If you need details for just one specific person, run `get_contact` by providing the unique contact ID. For structured data, use `list_groups` to get the names and IDs of every existing contact group in your system. You can then drill down further using `get_group` to fetch all the metadata associated with that specific contact batch. **Message History and Validation** You need an audit trail? Run `list_messages`, and your agent pulls a summary of recent SMS activity, showing who sent texts, who received them, and what their current delivery status is. To check the full details—including the complete text body and final delivery status—of one specific communication, use `get_message` with its unique ID. Before sending anything, you gotta make sure those phone numbers are actually active. Run `list_hlr`; this checks the Home Location Register (HLR) requests, telling you if a number is valid or currently connected to the network. **System Overview and Setup** To see what channels your account supports—whether it's SMS, voice, etc.—run `list_channels`. You can also check which types of groups exist by calling `list_groups` for a quick rundown of all available group names and IDs. This server turns complicated messaging workflows into simple commands for your agent. It handles everything from sending bulk texts to running deep audits on your client's connected data. ## Tools ### get_balance Gets the current dollar amount available in your MessageBird account. ### get_contact Retrieves detailed information for a single, specific contact ID. ### get_group Fetches the details and metadata associated with a specified contact group. ### get_message Gets the full text and status for one specific message ID. ### list_channels Lists all configured communication channels connected to your account. ### list_contacts Pulls a list of contacts, including metadata for multiple users. ### list_groups Retrieves the names and IDs of all existing contact groups. ### list_hlr Checks Home Location Register (HLR) requests to verify if a phone number is active on the network. ### list_messages Lists recent SMS messages, showing sender, recipient, and status history. ### send_sms Sends a new SMS text message to specified recipients globally. ## Prompt Examples **Prompt:** ``` Check my MessageBird account balance. ``` **Response:** ``` I've retrieved your balance. You currently have $50.00 available in your account. The payment type is set to PREPAID. ``` **Prompt:** ``` List the last 5 SMS messages sent from my account. ``` **Response:** ``` I've found your recent messages. You have 5 sent SMS, including one to +123456789 with status 'delivered'. Would you like the full text for any of them? ``` **Prompt:** ``` Send SMS 'Your discount code is VINKIUS20' to +15550123. ``` **Response:** ``` Message delivered! I've successfully sent the discount code to +15550123. The originator was set to 'Vinkius'. The message ID is xxxxxxxx. ``` ## Capabilities ### Send SMS Messages The agent sends a text message using `send_sms` and receives immediate confirmation of the transaction. ### Check Account Limits It calls `get_balance` to pull your current available funds, letting you monitor spending on the fly. ### Audit Contacts and Groups Using `list_contacts` or `list_groups`, the agent pulls lists of users or groups from your database for review. ### Review Message History The agent uses `list_messages` to retrieve and summarize recent SMS activity, including delivery status. ### Validate Numbers Running the `list_hlr` tool checks if a phone number is valid or active on the network. ## Use Cases ### Emergency Outage Alert The Ops Manager needs to notify 20 key stakeholders about a system outage. They ask their agent, 'Send SMS: System down for maintenance' using `send_sms` targeting the pre-approved group ID. The agent executes the send and confirms delivery status for all 20 recipients instantly. ### Marketing List Cleanup The Marketing Lead needs to run a campaign, but isn't sure if their new contact list is valid. They ask the agent to `list_contacts` and then use `get_group` on the resulting group ID. The agent verifies the list details and confirms readiness for broadcast. ### Support Ticket Audit A customer calls about a disputed message. The Support Specialist asks their agent to `list_messages` for that user's account history, then uses `get_message` on the ID provided by the customer. The agent pulls the full text and delivery status immediately. ### Pre-Deployment Validation Before sending a large batch of verification codes, the developer asks the agent to run `list_hlr` against 5 key numbers. This confirms the network validity for every recipient, preventing costly failures and ensuring service reliability. ## Benefits - Sends SMS messages and tracks delivery status. You use `send_sms` to push the text out, and the agent reports back on success or failure immediately, so you know your message arrived. - Maintains financial control using `get_balance`. Instead of guessing if funds are low, check the real-time balance directly in your workflow before sending any high-volume texts. - Audits entire contact structures. Running `list_contacts` or `list_groups` pulls metadata for hundreds of users, letting you verify who's on the list without exporting a spreadsheet first. - Verifies network status with `list_hlr`. If you suspect a number is dead or invalid, this tool checks its Home Location Register status before wasting credits on a failed send. - Provides clear message history. The agent uses `list_messages` to pull the last 50 texts sent, letting Support quickly review past interactions without navigating to an old inbox view. ## How It Works The bottom line is: you talk to your AI agent, and it talks to MessageBird via these tools for you. 1. Subscribe to the MessageBird MCP Server and provide your API key. 2. Your AI client recognizes the intent (e.g., 'Check my account balance'). 3. The agent executes the corresponding tool (`get_balance`) and returns the structured data directly into the conversation. ## Frequently Asked Questions **How do I check if my MessageBird account has enough money using get_balance?** You ask your agent, 'What is the current balance?' The agent executes `get_balance` and reports the exact available amount. It's faster than logging into the financial portal. **Can I send an SMS using send_sms to a whole list of contacts?** Yes, you tell your agent which group ID or list of numbers to target. The `send_sms` tool sends the message and reports on the delivery status for each recipient. **What is the difference between list_contacts and get_contact?** `list_contacts` pulls a roster, giving you metadata for many people at once. `get_contact` requires one specific ID to pull all the details for just that single user. **Should I use list_hlr or check network status manually?** Use `list_hlr`. This tool runs a formal Home Location Register request, which is the definitive way to verify if a number is active and valid on the current telecom network. **How do I review old messages with list_messages?** You ask your agent to 'List my recent texts.' The agent runs `list_messages` and provides a summary of all recent activity, including who got the message and if it delivered. **How do I use get_group to verify the members of a specific contact group?** It returns all member details for that group. You can check if the right contacts were added before running any broadcast campaigns. **If I run list_hlr, what should I do if the network lookup fails or returns an error code?** The tool provides specific failure codes and reasons for the lookup. You can cross-reference those codes to understand exactly what connectivity issue you're facing. **What does list_channels show me about my active communication setup?** This function lists every configured channel available through MessageBird. It confirms if your required pathways are correctly set up for broadcasting across different services. **How do I find my MessageBird API Key?** Log in to your [**MessageBird Dashboard**](https://dashboard.messagebird.com/), navigate to **Developers** > **API Access**, and you will find your Access Key there. Copy and paste it into the field below. **Can the agent check my current credit balance?** Yes. Use the `get_balance` tool. Your agent will retrieve your current account balance and payment type (prepaid/postpaid) instantly. **Is it possible to send SMS to multiple recipients at once?** Yes. The `send_sms` tool accepts a comma-separated list of recipient numbers. Your agent will deliver the message to all recipients and provide the overall delivery status.