tcxc-mcp-server

# TCXC MCP Server [](LICENSE) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io) The **TCXC MCP Server** is an open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects AI assistants — Claude, OpenAI, Cursor, and any MCP-compatible client — to the [TelecomsXChange (TCXC)](https://www.telecomsxchange.com) wholesale telecommunications marketplace. It exposes **55 tools and 7 guided workflows** for voice termination, SMS messaging, DID phone numbers, eSIM data packages, HLR lookups, and carrier account management, so telecom operators and developers can run wholesale telecom operations in plain English. ## What Can AI Assistants Do With It? | Capability | What your AI assistant can do | |---|---| | **Voice Termination** | Search carrier rates by prefix, run A/B route test calls, analyze CDRs and call quality (ASR/ACD) | | **SMS Services** | Compare global SMS termination rates, review delivery history and traffic summaries | | **DID Numbers** | Search, purchase, and configure virtual phone numbers (voice, SMS, fax capable) | | **eSIM Exchange** | Browse data packages by country, purchase eSIMs, top up, and track orders | | **Number Intelligence** | Live HLR lookups, portability data, and fraud/reputation scoring | | **Financial** | Check buyer/seller balances and payment history in real time | | **Account Management** | Provision SIP/SMS sub-accounts, manage IPs, block/unblock accounts | | **Analytics** | Live calls, top routes, traffic summaries, and performance insights | Example requests once connected: > "What's my TCXC account balance?" > > "Search voice rates for prefix 44 and compare the top 3 carriers" > > "Find eSIM data packages for Turkey and buy the cheapest 5GB option" ## Quick Start Three steps: install → add your TCXC credentials → connect your AI client. ### 1. Install Requires Python 3.10+ and a [TelecomsXChange (TCXC)](https://www.telecomsxchange.com) or [NeuTRAFIX (NTX)](https://www.neutrafix.net) account. ```bash # Clone and navigate git clone https://github.com/TelecomsXChangeAPi/tcxc-mcp-server.git cd tcxc-mcp-server # Setup virtual environment python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt # Create your config from the template cp .env.example .env ``` ### 2. Add Your TCXC Credentials Get your API credentials from your dashboard: - **TCXC**: [members.telecomsxchange.com](https://members.telecomsxchange.com) → Account → API Settings - **NeuTRAFIX**: [members.neutrafix.net](https://members.neutrafix.net) → Account → API Settings Edit `.env`: ```env # Buyer credentials (required) TCXC_USERNAME=your_username TCXC_API_KEY=your_api_key # Seller credentials (required) TCXC_SELLER_USERNAME=your_seller_username TCXC_SELLER_API_KEY=your_seller_api_key # API endpoint # NeuTRAFIX users: change the base URL to https://apiv2.neutrafix.net TCXC_API_BASE_URL=https://apiv2.telecomsxchange.com ``` Both buyer and seller credentials must be provided for the server to start. ### 3. Connect Your AI Client The server speaks standard MCP over stdio and works with every major MCP client: | AI Client | Setup | |---|---| | Claude Desktop | JSON config (below) | | Claude Code | `claude mcp add` one-liner | | OpenAI Codex CLI | `codex mcp add` one-liner | | Cursor | JSON config (below) | | Any MCP client | Point it at `start_mcp_server.sh` | In every case, use **absolute paths** and restart the client after changing its config. #### Claude Desktop Add to the config file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json` ```json { "mcpServers": { "tcxc": { "command": "/absolute/path/to/tcxc-mcp-server/start_mcp_server.sh" } } } ``` #### Claude Code (CLI) ```bash claude mcp add tcxc /absolute/path/to/tcxc-mcp-server/start_mcp_server.sh ``` #### OpenAI Codex CLI ```bash codex mcp add tcxc /absolute/path/to/tcxc-mcp-server/start_mcp_server.sh ``` Or add to `~/.codex/config.toml`: ```toml [mcp_servers.tcxc] command = "/absolute/path/to/tcxc-mcp-server/start_mcp_server.sh" ``` #### Cursor Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project): ```json { "mcpServers": { "tcxc": { "command": "/absolute/path/to/tcxc-mcp-server/start_mcp_server.sh" } } } ``` #### Any Other MCP Client Point your client at the wrapper script (which loads credentials from `.env`): ``` command: /absolute/path/to/tcxc-mcp-server/start_mcp_server.sh ``` Or run the Python entry point directly and pass credentials as environment variables: ``` command: /absolute/path/to/tcxc-mcp-server/venv/bin/python args: ["/absolute/path/to/tcxc-mcp-server/src/tcxc_mcp/server.py"] env: TCXC_USERNAME, TCXC_API_KEY, TCXC_SELLER_USERNAME, TCXC_SELLER_API_KEY ``` ## Running Standalone ```bash # Activate environment source venv/bin/activate # Start server ./start_mcp_server.sh # Or run directly python src/tcxc_mcp/server.py ``` ## Testing Use the interactive client to test tools: ```bash source venv/bin/activate python src/tcxc_mcp/mcp_client.py ``` Interactive commands: - `list_tools` - Show all available tools - `call_tool <name> <json_params>` - Execute a tool - `list_prompts` - Show guided workflows - `get_prompt <name> <json_args>` - Get workflow guidance ## Available Tools ### Voice Operations ```python search_voice_market(prefix="1", route_type="CLI") get_voice_destinations(country="United States") list_call_records(date_from="2026-01-01", date_to="2026-01-31") test_voice_route(i_account="123", cld1="+12125551234", cli1="+12025551234", i_connection1="8721", ...) ``` ### SMS Operations ```python marketview_search_sms(prefix="44", country="United Kingdom") buyers_smshistory(date_from="2026-01-01", date_to="2026-01-31") buyers_sms_summary(date_from="2026-01-01", date_to="2026-01-31") ``` ### DID Management ```python number_market(country="United States", did_type="mobile") number_list(prefix="1") number_purchase(i_did="12345", billing_i_account="123", contact="sip:user@domain.com") ``` ### eSIM Exchange ```python esim_countries() esim_market(country="Turkey") esim_purchase(i_esim_package="456", i_account="123") esim_list() esim_topup_list(iccid="8944500000000000000") esim_topup_purchase(iccid="8944500000000000000", package_type_id="789", i_account="123") esim_orders(date_from="2026-01-01", date_to="2026-01-31") ``` ### Financial & Account ```python buyers_balance() seller_balance() buyers_payhistory(date_from="2026-01-01", date_to="2026-01-31") buyers_account_list() ``` ### Utilities ```python hlr_lookup(number="+12125551234", i_account="123") get_number_score(phone_number="+12125551234") tools_country_codes() ``` **Full tool list**: 55 tools available. See [tool documentation](docs/TOOLS.md) for details. ## Guided Workflows (Prompts) The server includes intelligent prompts for complex tasks: - **search_best_voice_rates** - Find and compare voice carriers - **monitor_account_health** - Comprehensive account health check - **purchase_did_workflow** - Guided DID purchase process - **analyze_call_quality** - CDR analysis and quality insights - **sms_market_research** - SMS carrier comparison - **validate_routing_setup** - Test and validate phone routing - **compare_carriers** - Head-to-head carrier comparison Use prompts in Claude: "Use the monitor_account_health prompt to check my TCXC account" See [PROMPTS.md](PROMPTS.md) for the full guide. ## Troubleshooting ### Server won't start ```bash # Check environment variables cat .env ``` Confirm all four credential variables are set (buyer and seller). ### Authentication fails ```bash # Test credentials directly curl -u "$TCXC_USERNAME:$TCXC_API_KEY" \ --digest \ "$TCXC_API_BASE_URL/buyers/balance" ``` ### Import errors ```bash # Reinstall dependencies pip install -r requirements.txt # For HTTP/2 support pip install "httpx[http2]" ``` ### Claude Desktop connection issues - Use absolute paths (no `~` or relative paths) - Restart Claude Desktop after config changes - Check Claude logs: `tail -f ~/.config/claude/mcp.log` ## Development ```bash # Install dev dependencies pip install -e ".[dev]" # Format code make format # Run linting make lint # Type checking make typecheck # Run tests make test ``` ## Architecture - **Framework**: FastMCP (official MCP Python SDK) - **HTTP Client**: HTTPX with HTTP/2 and digest auth - **Authentication**: Dual account support (buyer/seller) - **Security**: Input validation, TLS 1.2+, rate limiting - **Performance**: Async/await, connection pooling ## Security - Credentials stored in `.env` (never committed to git) - File permissions: `chmod 600 .env` and `chmod 700 start_mcp_server.sh` - All inputs validated and sanitized before API calls - TLS verification enforced (TLS 1.2+) - Error messages sanitized to prevent information disclosure See [SECURITY.md](SECURITY.md) for detailed security practices. ## Environment Support **Production**: `https://apiv2.telecomsxchange.com` - Real billing and provisioning - Use production credentials **Sandbox**: Contact TCXC support for sandbox endpoint - Safe testing environment - No real billing impact ## Frequently Asked Questions ### What is the TCXC MCP Server? The TCXC MCP Server is an open-source Python implementation of the Model Context Protocol that gives AI assistants direct, secure access to the TelecomsXChange wholesale telecom API. Instead of writing REST integration code, you connect the server to Claude, OpenAI, or another MCP client and ask for what you need in natural language — search carrier rates, test voice routes, buy DID numbers or eSIMs, run HLR lookups, and monitor traffic. It ships with 55 tools and 7 guided workflow prompts, uses HTTP Digest Authentication with TLS 1.2+, and validates every input before it reaches the API. ### Which AI assistants and tools work with it? Any MCP-compatible client. Tested configurations include Claude Desktop, Claude Code (CLI), OpenAI Codex CLI, and Cursor. The server communicates over standard MCP stdio, so agent frameworks that support MCP — such as the OpenAI Agents SDK and Claude Agent SDK — can use it too. ### What do I need to get started? Three things: Python 3.10 or newer, a TelecomsXChange or NeuTRAFIX account, and your API credentials from the member dashboard (Account → API Settings). Setup takes about five minutes: clone the repo, install dependencies, copy `.env.example` to `.env`, add your credentials, and register the server with your AI client. ### Does it work with NeuTRAFIX? Yes. NeuTRAFIX runs the same platform API. Set `TCXC_API_BASE_URL=https://apiv2.neutrafix.net` in your `.env` and use your NTX credentials — everything else works identically. ### Is it free to use? The server itself is free and MIT-licensed. API usage is billed by TelecomsXChange at standard marketplace rates — voice, SMS, DID, and eSIM purchases made through the tools are real transactions on your TCXC account. ### Can an AI agent make purchases autonomously? Purchase tools (`number_purchase`, `esim_purchase`, `esim_topup_purchase`) execute real transactions against your account balance. MCP clients like Claude Desktop ask for your approval before each tool call by default; we recommend keeping approval prompts enabled for purchase and account-management tools. ### How is it secured? Credentials stay local in a gitignored `.env` file and are sent only to the TCXC API over HTTPS using HTTP Digest Authentication. The client enforces TLS 1.2+ with strong cipher suites, whitelists API endpoints, validates and sanitizes all inputs, rate-limits requests, and strips sensitive data from error messages and logs. See [SECURITY.md](SECURITY.md). ### What is TelecomsXChange? [TelecomsXChange](https://www.telecomsxchange.com) is a wholesale telecommunications marketplace where licensed carriers, operators, and communication service providers buy and sell voice termination, SMS, DID numbers, and eSIM data packages. Buyers get transparent per-route pricing with quality metrics (ASR/ACD); sellers reach a global base of interconnected buyers through one API. ## License MIT License - see [LICENSE](LICENSE) file ## Support - **Issues**: [GitHub Issues](https://github.com/TelecomsXChangeAPi/tcxc-mcp-server/issues) - **TCXC Support**: [telecomsxchange.com/contact](https://www.telecomsxchange.com/contact) - **API Docs**: [apidocs.telecomsxchange.com](https://apidocs.telecomsxchange.com) - **Dashboard**: [members.telecomsxchange.com](https://members.telecomsxchange.com) ## Contributing Contributions welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Make your changes with tests 4. Submit a pull request --- **Built with the** [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) | **Powered by** [TelecomsXChange](https://www.telecomsxchange.com)