nrjchnd voipbin mcp

A Model Context Protocol (MCP) server implementation for the VoIPBin API, enabling AI models to interact with VoIP services.

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.

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.

• 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

• get_calls: Retrieve a list of calls with optional filtering
• get_call: Get details of a specific call
• create_call: Create a new call
• end_call: End an active call

• get_agents: Retrieve a list of agents
• get_agent: Get details of a specific agent
• update_agent_status: Update an agent's status

• get_campaigns: Retrieve a list of campaigns
• get_campaign: Get details of a specific campaign
• create_campaign: Create a new campaign

• get_recordings: Retrieve a list of call recordings
• get_recording: Get details of a specific recording

• get_queues: Retrieve a list of call queues
• get_queue: Get details of a specific queue

• get_conferences: Retrieve a list of active conferences
• create_conference: Create a new conference

• get_chats: Retrieve a list of chat conversations
• send_chat_message: Send a message in a chat conversation

• get_billing_info: Retrieve current billing information
• get_billing_history: Retrieve billing history with optional date filtering

1. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

1. Install dependencies:

pip install -r requirements.txt

1. Create a .env file:

cp .env.example .env

1. Update the .env file with your VoIPBin API credentials:

VOIPBIN_API_URL=https://api.voipbin.net/v1.0
VOIPBIN_API_KEY=your-api-key-here
PORT=8000

1. 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

1. 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

python src/main.py --transport stdio

python src/main.py --transport sse --port 8000

The server runs in SSE mode by default when using Docker. The container exposes port 8000 for SSE connections.

{
  "name": "create_call",
  "arguments": {
    "body": {
      "phone_number": "+1234567890",
      "agent_id": "agent_123",
      "campaign_id": "campaign_456"
    }
  }
}

{
  "name": "get_call",
  "arguments": {
    "call_id": "call_789"
  }
}

{
  "name": "create_conference",
  "arguments": {
    "body": {
      "name": "Team Meeting",
      "participants": ["+1234567890", "+0987654321"]
    }
  }
}

{
  "name": "send_chat_message",
  "arguments": {
    "chat_id": "chat_123",
    "body": {
      "message": "Hello, how can I help you today?"
    }
  }
}

Each tool includes annotations that provide metadata about its behavior:

• readOnlyHint: Indicates if the tool only reads data
• destructiveHint: Indicates if the tool modifies or deletes data
• idempotentHint: Indicates if repeated calls have the same effect as a single call
• openWorldHint: Indicates if the tool operates in an open world context

The server includes comprehensive error handling:

• Invalid API credentials
• Network connectivity issues
• Invalid request parameters
• Rate limiting
• Server errors

To add a new tool:

1. Add the tool definition in the list_tools() function
2. Implement the tool handler in the voipbin_tool() function
3. Update the documentation

Run the test suite:

python -m pytest tests/

• 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

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

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.

• Use it commercially
• Modify it
• Distribute it
• Use it privately
• Sublicense it

• Include the original copyright notice
• Include the license text
• Provide clear attribution to the original source
• Maintain attribution in any derivative works

• 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/.