Metadata-Version: 2.4
Name: twilio-manager-mcp
Version: 0.1.5
Summary: Twilio Manager MCP connects Claude AI or any host to Twilio through the Model Context Protocol (MCP)
Project-URL: Homepage, https://github.com/errajibadr/twilio-manager-mcp
Project-URL: Bug Tracker, https://github.com/errajibadr/twilio-manager-mcp/issues
Author-email: Erraj Badr <errajibadr@gmail.com>
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: mcp[cli]>=1.4.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: twilio>=9.5.1
Description-Content-Type: text/markdown

# TwilioManager MCP - Twilio Model Context Protocol Integration

TwilioManager MCP connects Claude AI to Twilio through the Model Context Protocol (MCP), enabling Claude to interact directly with Twilio's API. This integration allows for prompt-assisted Twilio account management, subaccount creation, phone number management, and regulatory compliance handling.


    
## Features

- **Two-way communication**: Connect Claude AI to Twilio through a socket-based server
- **Subaccount management**: Create, list, and manage Twilio subaccounts
- **Phone number control**: Transfer, configure, and manage phone numbers across accounts
- **Regulatory compliance**: Manage regulatory bundles and compliance requirements
- **Address management**: Create and manage addresses for regulatory compliance
- **Asynchronous API**: High-performance async implementation of Twilio API interactions

## Components

The system consists of two main components:

- **MCP Server** (`twilio_manager_mcp.py`): A Python server that implements the Model Context Protocol and provides tools for Twilio management
- **Async Twilio API** (`api/async_twilio_api.py`): An asynchronous wrapper around the Twilio API for efficient operations

## Installation

### Prerequisites

- Python 3.10 or newer
- `uv` 

#### If you're on Mac:
```
brew install uv
```

#### On Windows:
```
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
set Path=C:\Users\[USERNAME]\.local\bin;%Path%
```

⚠️ Do not proceed before installing UV

### Claude for Desktop Integration

Go to Claude > Settings > Developer > Edit Config > `claude_desktop_config.json` to include the following:

```json
{
    "mcpServers": {
        "twilio": {
            "command": "uvx",
            "args": [
                "twilio-manager-mcp"
            ]
        }
    }
}
```

### Cursor Integration

Run twilio-manager-mcp without installing it permanently through uvx. Go to Cursor Settings > MCP and paste this in the Json

```
{
    "mcpServers":{
        "twilio_manager_mcp": {
            "command": "uvx",
            "args": ["twilio-manager-mcp"],
            "env": {
                "TWILIO_ACCOUNT_SID": "AC00000000000000000000000000000000",
                "TWILIO_AUTH_TOKEN": "00000000000000000000000000000000"
            }
        }
    }
)
```

⚠️ Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both

### Environment Setup

1. Clone this repository
2. Copy `.env.example` to `.env` and fill in your Twilio credentials:
   ```
   TWILIO_ACCOUNT_SID=your_account_sid
   TWILIO_AUTH_TOKEN=your_auth_token
   ```
3. Install dependencies:
   ```
   uv pip install -e .
   ```

## Usage

### Starting the Connection

1. Make sure your credentials are set in the `.env` file
2. Start the MCP server:
   ```
   uvx twilio-manager-mcp
   ```
3. In Claude, look for the Twilio MCP tool icon in the toolbar

### Using with Claude

Once the config file has been set on Claude and the MCP server is running, you will see a tool icon for the Twilio Manager MCP.

### Capabilities

- List and filter Twilio subaccounts
- View phone numbers associated with accounts
- Transfer phone numbers between accounts
- Create and manage addresses
- Handle regulatory compliance and bundles
- Execute comprehensive Twilio account management tasks

### Example Commands

Here are some examples of what you can ask Claude to do:

- "List all my Twilio subaccounts"
- "Show all phone numbers on my main account"
- "Transfer phone number X from account A to account B"
- "Create a new address for regulatory compliance"
- "Duplicate a regulatory bundle to a subaccount"
- "Show all phone numbers of a specific type"

## Troubleshooting

- **Connection issues**: Make sure the MCP server is running, and the MCP server is configured on Claude
- **Authentication errors**: Verify your Twilio credentials in the `.env` file
- **Rate limiting**: Twilio API has rate limits; consider adding delays between operations if hitting limits
- **Timeout errors**: Try simplifying your requests or breaking them into smaller steps

## Technical Details

### Communication Protocol

The system uses a JSON-based protocol over TCP sockets:

- Commands are sent as JSON objects with a type and optional params
- Responses are JSON objects with status and result or message

### Async Implementation

The Twilio API wrapper uses Python's asyncio for high-performance, non-blocking operations:

- Custom `AsyncTwilioHttpClient` for managing HTTP requests asynchronously
- Context manager pattern for resource management
- Error handling and retry logic

## Limitations & Security Considerations

- The system requires valid Twilio credentials with appropriate permissions
- Keep your `.env` file secure and never commit it to version control
- Consider adding additional validation for critical operations
- API keys should be rotated regularly for security
- Some operations may require multiple steps to complete successfully

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Disclaimer

This tool interacts with a paid service (Twilio). Be aware that API calls made through this tool may incur charges to your Twilio account. Always test in development environments before using in production.
