webvoice-mcp

WebVoice MCP Server

Local Model Context Protocol server that exposes WebVoice REST API tools to Cursor, Claude Desktop, and other MCP clients.

Install from PyPI:

pip install webvoice-mcp

From source (development)

pip install -r requirements-mcp.txt
# or editable install from repo root:
pip install -e .

Configure Cursor

Option A — Agent registration via MCP (no browser)

• Add MCP without WEBVOICE_API_KEY first (or use the register tools from any client).
• Call webvoice_register_send_code with your email.
• Read the OTP from email, then webvoice_register_verify with the code.
• Response includes api_key (once), onboarding.credits, onboarding.can_use_api, and optional onboarding.solana (wallet + memo_code for USDC/SOL top-up).
• If can_use_api is true, use chat/TTS/STT immediately with welcome credits.
• Set WEBVOICE_API_KEY in MCP config and restart Cursor (optional Solana/PayPal top-up later).

REST equivalent: POST /api/v1/auth/send-code/ → POST /api/v1/auth/verify-code/ with create_api_key: true. See API docs.

Option B — Browser signup (human)

• Login — email OTP or Google (/accounts/login/). New users get welcome + daily free credits.
• API key — API dashboard → Create key → copy wv_… (shown once).
• Credits (optional) — Buy credits, Premium (PayPal), or Solana (send USDC/SOL with your personal memo from webvoice_onboarding).

When balance is zero, MCP calls fail with insufficient credits; you receive an email with a recharge link.

MCP config

Edit Cursor MCP config (~/.cursor/mcp.json or Settings → MCP):

{
  "mcpServers": {
    "webvoice": {
      "command": "webvoice-mcp",
      "env": {
        "WEBVOICE_API_KEY": "wv_your_key_here"
      }
    }
  }
}

If webvoice-mcp is not on PATH, use Python module form:

{
  "mcpServers": {
    "webvoice": {
      "command": "python",
      "args": ["-m", "webvoice_mcp"],
      "cwd": "/path/to/webvoice",
      "env": {
        "WEBVOICE_API_KEY": "wv_your_key_here"
      }
    }
  }
}

Optional: WEBVOICE_BASE_URL (default https://webvoice.easytaskflow.app/api/v1).

Tools

Tool	Description
webvoice_register_send_code	Start registration — OTP to email
webvoice_register_verify	Complete registration → API key + onboarding (credits, can_use_api)
webvoice_onboarding	Credits, can_use_api, optional Solana wallet/memo, recharge URLs
webvoice_status	Credits balance
webvoice_list_chat_models	Available chat models
webvoice_list_voices	TTS voices
webvoice_chat	Chat completions (DeepSeek default)
webvoice_tts	Text-to-speech → MP3
webvoice_stt	Transcribe local audio file
webvoice_translate	Text translation
webvoice_image	MiniMax image generation

Example agent flow

New agent (register → use → optional top-up):

• webvoice_register_send_code → webvoice_register_verify → save api_key.
• If onboarding.can_use_api: call webvoice_chat / webvoice_tts / … immediately.
• Optional: webvoice_onboarding → Solana memo or PayPal URLs when you need more credits.

Existing account:

• Ask the model to call webvoice_chat with your question.
• Call webvoice_tts with output_path to save spoken reply.
• Call webvoice_stt with a recorded audio_path for voice input.

Credits are billed on your WebVoice account per API call.