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.