luxiaolei/comm-mcps
If you are the rightful owner of comm-mcps and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Communications MCP Server is a robust Model Context Protocol server designed to facilitate email, Telegram, and Signal communications for Claude Code, ensuring reliable and type-safe communication workflows.
Communications MCP Server
A comprehensive Model Context Protocol (MCP) server that provides email, Telegram, and Signal communication tools for Claude Code. Built with FastMCP for reliable, type-safe communication workflows.
Features
- š§ Email - One-way communication via Resend API
- š± Telegram - Bidirectional messaging with bot integration
- š¬ Signal - Bidirectional messaging via signal-cli wrapper
- āļø Auto-configuration - Smart setup with environment detection
- š Type Safety - Full type hints and validation
- ā±ļø Timeout Handling - Configurable timeouts (default: 3 minutes)
Installation
Method 1: Install from GitHub (Recommended)
pip install git+https://github.com/luxiaolei/comm-mcps.git
Method 2: Update/Reinstall
pip install --upgrade git+https://github.com/luxiaolei/comm-mcps.git
Method 3: Development Setup
git clone https://github.com/luxiaolei/comm-mcps.git
cd comm-mcps
./setup.sh
Quick Start
-
Create environment configuration:
# Create .env file with your credentials cat > .env << EOF # Email (Resend) RESEND_API_KEY=your_resend_api_key FROM_EMAIL=noreply@resend.dev # Telegram TELEGRAM_BOT_TOKEN=your_bot_token TELEGRAM_API_ID=your_api_id TELEGRAM_API_HASH=your_api_hash TELEGRAM_CHAT_ID=your_chat_id # Signal SIGNAL_PHONE_NUMBER=+1234567890 SIGNAL_CLI_PATH=signal-cli EOF
-
Use as CLI:
# Check status comm-mcps-cli status # Send email comm-mcps-cli email "Alert" "Your message" # Send Telegram (bidirectional) comm-mcps-cli telegram "Hello" --reply --timeout 60 # Send Signal (bidirectional) comm-mcps-cli signal "Hello" "+1234567890" --reply
-
Use as Python library:
import asyncio from comm_mcps.tools.email import send_email # Send notification result = asyncio.run(send_email("user@example.com", "Alert", "Message"))
-
Use with Claude Code MCP:
# Step 1: Install the package globally pip install git+https://github.com/luxiaolei/comm-mcps.git # Step 2: Create .env with your credentials in your project cd your-project-directory cat > .env << EOF RESEND_API_KEY=your_key TELEGRAM_BOT_TOKEN=your_token TELEGRAM_CHAT_ID=your_chat_id SIGNAL_PHONE_NUMBER=your_number EOF # Step 3: Create MCP configuration in your project cat > .mcp.json << EOF { "mcpServers": { "communications": { "command": "python3", "args": ["-m", "comm_mcps.server"] } } } EOF # Step 4: Start Claude Code claude # Communications tools will be available
Why this works:
- ā
pip install
makescomm_mcps
globally available - ā
python3 -m comm_mcps.server
finds the installed package - ā
.env
in working directory is automatically loaded - ā No hardcoded paths - works on any computer
- ā
Available Tools
Email Tool
email_tool
Send emails via Resend API (one-way notifications only).
Features:
- Uses
noreply@resend.dev
as sender (hardcoded) - Configurable default recipient via environment
- Returns simple status: "Email sent to {recipient}" or "Email failed: {error}"
{
"tool": "email_tool",
"args": {
"subject": "Trading Alert",
"body": "Your notification message",
"to": "recipient@example.com",
"html_body": "<h1>Optional HTML</h1>"
}
}
Telegram Tool
telegram_tool
Unified bidirectional Telegram messaging with 1-second polling.
Features:
- Uses
TELEGRAM_CHAT_ID
from environment (not argument) - Send messages and optionally wait for replies
- 1-second polling when
expected_reply=True
- Configure your own Telegram bot
{
"tool": "telegram_tool",
"args": {
"message": "Hello from Claude!",
"expected_reply": true,
"timeout": 180.0
}
}
Signal Tool
signal_tool
Unified bidirectional Signal messaging with 1-second polling.
Features:
- Send to any phone number or group ID
- Wait for replies with 1-second polling
- Uses your configured phone number as sender
- Secure end-to-end encryption
{
"tool": "signal_tool",
"args": {
"message": "Hello via Signal!",
"recipient": "+1234567890",
"expected_reply": true,
"timeout": 180.0
}
}
Status Tool
get_communication_status
Get configuration status for all services.
{
"tool": "get_communication_status",
"args": {}
}
Service Setup
Email (Resend)
- Sign up at resend.com
- Get your API key from the dashboard
- Add domain and verify sender email
- Set
RESEND_API_KEY
andFROM_EMAIL
in.env
Telegram
- Create a bot via @BotFather
- Get bot token from BotFather
- Get API credentials from my.telegram.org
- Set
TELEGRAM_BOT_TOKEN
,TELEGRAM_API_ID
, andTELEGRAM_API_HASH
in.env
Signal
- Install signal-cli (automated by setup.sh)
- Register your phone number:
signal-cli -u +1234567890 register
- Verify with SMS code:
signal-cli -u +1234567890 verify CODE
- Set
SIGNAL_PHONE_NUMBER
in.env
Development
Project Structure
comm_mcps/
āāā src/comm_mcps/
ā āāā server.py # Main FastMCP server
ā āāā config.py # Configuration management
ā āāā tools/
ā āāā email.py # Email tool implementation
ā āāā telegram.py # Telegram tools
ā āāā signal.py # Signal tools
āāā setup.sh # Setup script
āāā pyproject.toml # Project configuration
Running Locally
# Install dependencies
uv sync
# Run server
uv run python -m comm_mcps.server
# Test tools
uv run python -c "from comm_mcps.tools.email import get_email_status; print(get_email_status())"
Configuration Options
All tools support these standard parameters:
expected_reply: bool = False
- Whether to expect a responsetimeout: float = 180.0
- Operation timeout in seconds (3 minutes default)
Environment variables:
MCP_TRANSPORT
- Transport protocol (stdio, http, sse)LOG_LEVEL
- Logging level (DEBUG, INFO, WARNING, ERROR)
Error Handling
The server provides structured error responses:
{
"status": "error",
"error": "Descriptive error message"
}
Common error scenarios:
- Missing configuration (API keys, credentials)
- Network timeouts
- Service-specific errors (invalid recipients, rate limits)
- CLI tool unavailability (signal-cli)
Troubleshooting
Email Issues
- Verify Resend API key and sender domain
- Check sender email is verified in Resend dashboard
- Ensure recipient email format is valid
Telegram Issues
- Verify bot token with BotFather
- Check API ID/hash from my.telegram.org
- Ensure bot is added to target chats/groups
Signal Issues
- Verify signal-cli installation:
signal-cli --version
- Check phone number registration:
signal-cli -u +phone listIdentities
- Ensure signal-cli binary is in PATH
General Issues
- Check
.env
file exists and has correct values - Verify Python 3.10+ installation
- Run setup.sh to reinstall dependencies
License
MIT License - see LICENSE file for details.