{"id":50324989,"url":"https://github.com/jackccrawford/sendblue-mcp","last_synced_at":"2026-05-29T05:04:28.291Z","repository":{"id":347201818,"uuid":"1193108324","full_name":"jackccrawford/sendblue-mcp","owner":"jackccrawford","description":"SMS/iMessage for AI agents — secure, polling-based, no webhooks required.  Your agent needs to send campaign messages and check for replies. Traditional webhook approaches expose your local machine to the internet. Sendblue MCP uses API polling instead — zero attack surface, zero infrastructure, zero security risk.","archived":false,"fork":false,"pushed_at":"2026-03-27T01:02:30.000Z","size":57,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T13:51:41.598Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://agentdoor.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jackccrawford.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-26T22:09:32.000Z","updated_at":"2026-03-27T01:02:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jackccrawford/sendblue-mcp","commit_stats":null,"previous_names":["jackccrawford/sendblue-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jackccrawford/sendblue-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackccrawford%2Fsendblue-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackccrawford%2Fsendblue-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackccrawford%2Fsendblue-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackccrawford%2Fsendblue-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jackccrawford","download_url":"https://codeload.github.com/jackccrawford/sendblue-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackccrawford%2Fsendblue-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33637486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2026-05-29T05:04:14.984Z","updated_at":"2026-05-29T05:04:28.275Z","avatar_url":"https://github.com/jackccrawford.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sendblue MCP\n\nSMS/iMessage for AI agents — secure, polling-based, no webhooks required.\n\nYour agent needs to send campaign messages and check for replies. Traditional webhook approaches expose your local machine to the internet. Sendblue MCP uses API polling instead — zero attack surface, zero infrastructure, zero security risk.\n\n```python\n# Send a message\nsend_sms(number=\"+15551234567\", content=\"Campaign message here\")\n\n# Check for replies (no webhooks needed)\nlist_messages(is_outbound=False, limit=10)\n```\n\n47 messages later, across sessions, your agent remembers the conversation context.\n\n## About Sendblue\n\n[Sendblue](https://sendblue.co) is the SMS/iMessage API that powers this server. They handle message delivery, phone number management, iMessage detection, and delivery status tracking. This MCP server is a wrapper — it connects your AI agent to Sendblue's REST API using polling instead of webhooks.\n\nYou'll need a Sendblue account and API credentials to use this tool. Sign up at [sendblue.co](https://sendblue.co) and get your keys from the [dashboard](https://app.sendblue.co).\n\n**This project is not affiliated with Sendblue.** It's an independent open-source MCP server built on their public API.\n\n## End-to-end: what this actually looks like\n\n**Monday — Campaign launch.** Your agent sends 50 outreach messages:\n\n```python\nfor contact in campaign_list:\n    send_sms(number=contact.phone, content=personalized_message)\n```\n\n**Tuesday — Check responses.** Different session, different agent:\n\n```python\nreplies = list_messages(is_outbound=False, limit=50)\n# Agent sees: 12 replies, 3 interested, 9 opt-outs\n```\n\nNo webhook setup. No public endpoints. No ngrok. Just secure API polling.\n\n**Why polling beats webhooks for campaigns:**\n- ✅ No exposed services on your machine\n- ✅ No infrastructure to maintain\n- ✅ Campaign responses aren't real-time anyway\n- ✅ Zero security risk to genesis station\n- ✅ Works from anywhere (no static IP needed)\n\n## Works with everything\n\nWindsurf, Claude Desktop, any MCP-compatible client. One Poetry environment. No runtime dependencies beyond Python 3.11+.\n\n## Install\n\n**1. Clone and install:**\n\n```bash\ngit clone https://github.com/jackccrawford/sendblue-mcp.git\ncd sendblue-mcp\npoetry install --no-root\n```\n\n**2. Configure credentials:**\n\nCreate `~/.keys/sendblue.json`:\n\n```json\n{\n  \"api_key\": \"your_sendblue_api_key\",\n  \"secret_key\": \"your_sendblue_secret_key\",\n  \"from_number\": \"+15559876543\",\n  \"contacts\": {\n    \"alice\": \"+15551234567\",\n    \"bob\": \"+15559998888\"\n  }\n}\n```\n\nGet your credentials from [Sendblue Dashboard](https://app.sendblue.co).\n\n**3. Add to MCP config:**\n\nWindsurf (`~/.codeium/windsurf/mcp_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"sendblue\": {\n      \"command\": \"/Users/YOUR_USERNAME/.local/bin/poetry\",\n      \"args\": [\n        \"-C\",\n        \"/Users/YOUR_USERNAME/Dev/sendblue-mcp\",\n        \"run\",\n        \"python\",\n        \"src/server.py\"\n      ],\n      \"env\": {\n        \"FASTMCP_BANNER\": \"0\",\n        \"PYTHONWARNINGS\": \"ignore\"\n      }\n    }\n  }\n}\n```\n\nClaude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"sendblue\": {\n      \"command\": \"poetry\",\n      \"args\": [\"-C\", \"/path/to/sendblue-mcp\", \"run\", \"python\", \"src/server.py\"]\n    }\n  }\n}\n```\n\n**4. Restart your MCP client** (Windsurf, Claude Desktop, etc.)\n\n## What it looks like\n\n**Send a message:**\n\n```python\nsend_sms(\n    number=\"+15551234567\",\n    content=\"Test from Sendblue MCP! 🚀\"\n)\n# Returns: {\"status\": \"QUEUED\", \"message_handle\": \"...\", \"from_number\": \"+15559876543\"}\n```\n\n**Check for replies:**\n\n```python\nlist_messages(is_outbound=False, limit=10)\n# Returns: [{\"content\": \"Interested!\", \"from_number\": \"+15551234567\", ...}, ...]\n```\n\n**Get your contacts:**\n\n```python\nget_contacts()\n# Returns: [{\"name\": \"alice\", \"number\": \"+15551234567\"}, {\"name\": \"bob\", \"number\": \"+15559998888\"}]\n```\n\n**Check if a number supports iMessage:**\n\n```python\nevaluate_service_type(number=\"+15551234567\")\n# Returns: {\"number\": \"+15551234567\", \"service\": \"iMessage\"}\n```\n\n## How it works\n\nSendblue MCP is a FastMCP server backed by httpx for async API calls. No webhooks. No background services. No public endpoints.\n\n```\nAgent → MCP Server (FastMCP) → Sendblue API (HTTPS)\n```\n\nMessages are sent via Sendblue's REST API. Replies are retrieved by polling `/api/v2/messages` when you ask. Content stays in Sendblue's cloud until you fetch it.\n\n**Security model:**\n- Credentials stored locally in `~/.keys/sendblue.json` (mode 0600)\n- No public endpoints exposed\n- No webhook receivers\n- No attack surface on your machine\n- API calls are outbound-only (HTTPS to Sendblue)\n\n## Tools\n\n### `send_sms(number, content, send_style=None)`\n\nSend an SMS or iMessage via Sendblue.\n\n**Args:**\n- `number` (str): Phone number in E.164 format (e.g., `+15551234567`)\n- `content` (str): Message text to send\n- `send_style` (str, optional): Message style - `'invisible'`, `'gentle'`, `'loud'`, `'slam'`\n\n**Returns:**\n```json\n{\n  \"status\": \"QUEUED\",\n  \"message_handle\": \"35d2bd01-5fe0-4ee3-a9fd-a61231e0ddd4\",\n  \"from_number\": \"+15559876543\",\n  \"to_number\": \"+15551234567\",\n  \"date_sent\": \"2026-03-26T22:14:40.696Z\"\n}\n```\n\n### `list_messages(limit=10, is_outbound=False, offset=0)`\n\nList recent messages (inbound or outbound). Polls Sendblue API without requiring webhooks.\n\n**Args:**\n- `limit` (int): Number of messages to retrieve (default: 10, max: 100)\n- `is_outbound` (bool): `False` for received messages, `True` for sent messages\n- `offset` (int): Pagination offset (default: 0)\n\n**Returns:**\n```json\n{\n  \"messages\": [\n    {\n      \"content\": \"Interested in learning more!\",\n      \"from_number\": \"+15551234567\",\n      \"to_number\": \"+15559876543\",\n      \"is_outbound\": false,\n      \"status\": \"RECEIVED\",\n      \"date_sent\": \"2026-03-26T22:30:15.123Z\"\n    }\n  ]\n}\n```\n\n### `get_contacts()`\n\nGet list of saved contacts from credentials file.\n\n**Returns:**\n```json\n[\n  {\"name\": \"alice\", \"number\": \"+15551234567\"},\n  {\"name\": \"bob\", \"number\": \"+15559998888\"}\n]\n```\n\n### `check_message_status(account_email, number)`\n\nCheck delivery status of messages.\n\n**Args:**\n- `account_email` (str): Your Sendblue account email\n- `number` (str): Phone number to check status for\n\n**Returns:**\n```json\n{\n  \"status\": \"DELIVERED\",\n  \"last_message\": \"2026-03-26T22:14:40.696Z\"\n}\n```\n\n### `evaluate_service_type(number)`\n\nCheck if a number can receive iMessage or SMS.\n\n**Args:**\n- `number` (str): Phone number in E.164 format\n\n**Returns:**\n```json\n{\n  \"number\": \"+15551234567\",\n  \"service\": \"iMessage\"\n}\n```\n\n## Security considerations\n\n**Why no webhooks?**\n\nTraditional webhook approaches require exposing your local machine to the internet (via ngrok, Tailscale Funnel, etc.). This creates an attack surface on your development machine where sensitive assets live (genesis station, credentials, code).\n\n**Polling is safer:**\n- No public endpoints\n- No inbound connections\n- No webhook receiver code to exploit\n- API calls are outbound-only\n- You control when messages are fetched\n\n**For sales campaigns, polling is sufficient:**\n- Responses aren't real-time (people take hours/days to reply)\n- Checking every few minutes is fast enough\n- Zero infrastructure complexity\n- Zero security risk\n\n**If you need real-time webhooks:**\n- Deploy webhook receiver on isolated server (not your Mac)\n- Use dedicated droplet with no privileged access\n- Forward messages to queue/database\n- MCP polls the queue (still no webhooks on your machine)\n\n## Dependencies\n\n- Python 3.11+\n- FastMCP 2.0+\n- httpx 0.28+\n- pydantic 2.10+\n\nAll managed via Poetry. No system dependencies.\n\n## License\n\nMIT\n\n## About\n\nBuilt for mVara's sales campaign automation. Designed for security-conscious teams who eliminated ngrok and need safe two-way messaging.\n\n**Repository:** https://github.com/jackccrawford/sendblue-mcp  \n**Issues:** https://github.com/jackccrawford/sendblue-mcp/issues  \n**Sendblue API:** https://docs.sendblue.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackccrawford%2Fsendblue-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjackccrawford%2Fsendblue-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackccrawford%2Fsendblue-mcp/lists"}