VoIPBin MCP Server
VoIPBin MCP Server
A Model Context Protocol (MCP) server implementation for the VoIPBin API, enabling AI models to interact with VoIP services.
Disclaimer
This software is provided "as is" without any warranties, either express or implied. The author makes no guarantees about the completeness, reliability, or accuracy of this software. Any use of this software is at your own risk. The author shall not be liable for any damages arising from the use of this software.
Overview
This MCP server provides a standardized interface for AI models to interact with VoIPBin's API services. It implements the Model Context Protocol specification and supports both SSE and stdio transport types.
Features
- Full VoIPBin API integration through MCP protocol
- Support for both stdio and SSE transport modes
- Comprehensive tool definitions with proper annotations
- Type-safe request/response handling
- Asynchronous HTTP requests
- Proper error handling and validation
- Docker support for easy deployment
Available Tools
Call Management
get_calls: Retrieve a list of calls with optional filteringget_call: Get details of a specific callcreate_call: Create a new callend_call: End an active call
Agent Management
get_agents: Retrieve a list of agentsget_agent: Get details of a specific agentupdate_agent_status: Update an agent's status
Campaign Management
get_campaigns: Retrieve a list of campaignsget_campaign: Get details of a specific campaigncreate_campaign: Create a new campaign
Recording Management
get_recordings: Retrieve a list of call recordingsget_recording: Get details of a specific recording
Queue Management
get_queues: Retrieve a list of call queuesget_queue: Get details of a specific queue
Conference Management
get_conferences: Retrieve a list of active conferencescreate_conference: Create a new conference
Chat Management
get_chats: Retrieve a list of chat conversationssend_chat_message: Send a message in a chat conversation
Billing Management
get_billing_info: Retrieve current billing informationget_billing_history: Retrieve billing history with optional date filtering
Setup
Local Development Setup
- Create a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install dependencies:
pip install -r requirements.txt
- Create a
.envfile:
cp .env.example .env
- Update the
.envfile with your VoIPBin API credentials:
VOIPBIN_API_URL=https://api.voipbin.net/v1.0
VOIPBIN_API_KEY=your-api-key-here
PORT=8000
Docker Setup
- Build and run using Docker Compose:
# Build and start the container
docker-compose up --build
# Run in detached mode
docker-compose up -d
# Stop the container
docker-compose down
- Or build and run using Docker directly:
# Build the image
docker build -t voipbin-mcp-server .
# Run the container
docker run -d \
-p 8000:8000 \
-e VOIPBIN_API_KEY=your-api-key-here \
-e VOIPBIN_API_URL=https://api.voipbin.net/v1.0 \
voipbin-mcp-server
Running the Server
Local Development
Standard I/O Mode
python src/main.py --transport stdio
SSE Mode
python src/main.py --transport sse --port 8000
Docker
The server runs in SSE mode by default when using Docker. The container exposes port 8000 for SSE connections.
Tool Usage Examples
Creating a Call
{
"name": "create_call",
"arguments": {
"body": {
"phone_number": "+1234567890",
"agent_id": "agent_123",
"campaign_id": "campaign_456"
}
}
}
Getting Call Details
{
"name": "get_call",
"arguments": {
"call_id": "call_789"
}
}
Creating a Conference
{
"name": "create_conference",
"arguments": {
"body": {
"name": "Team Meeting",
"participants": ["+1234567890", "+0987654321"]
}
}
}
Sending a Chat Message
{
"name": "send_chat_message",
"arguments": {
"chat_id": "chat_123",
"body": {
"message": "Hello, how can I help you today?"
}
}
}
Tool Annotations
Each tool includes annotations that provide metadata about its behavior:
readOnlyHint: Indicates if the tool only reads datadestructiveHint: Indicates if the tool modifies or deletes dataidempotentHint: Indicates if repeated calls have the same effect as a single callopenWorldHint: Indicates if the tool operates in an open world context
Error Handling
The server includes comprehensive error handling:
- Invalid API credentials
- Network connectivity issues
- Invalid request parameters
- Rate limiting
- Server errors
Development
Adding New Tools
To add a new tool:
- Add the tool definition in the
list_tools()function - Implement the tool handler in the
voipbin_tool()function - Update the documentation
Testing
Run the test suite:
python -m pytest tests/
Security
- API keys are stored securely in environment variables
- All requests are authenticated
- HTTPS is enforced for API communication
- Input validation is performed on all requests
- Docker container runs as non-root user
- Health checks ensure container is running properly
Contributing
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
The MIT License is a permissive license that is short and to the point. It lets people do anything they want with the code as long as they provide attribution back to you and don't hold you liable.
What you can do with this code:
- Use it commercially
- Modify it
- Distribute it
- Use it privately
- Sublicense it
What you must do:
- Include the original copyright notice
- Include the license text
- Provide clear attribution to the original source
- Maintain attribution in any derivative works
What you cannot do:
- Hold the author liable for damages
- Remove or obscure the attribution
- Claim the work as your own
For more information about the MIT License, visit choosealicense.com/licenses/mit/.