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)

1. Add MCP without WEBVOICE_API_KEY first (or use the register tools from any client).
2. Call webvoice_register_send_code with your email.
3. Read the OTP from email, then webvoice_register_verify with the code.
4. Response includes api_key (once), onboarding.credits, onboarding.can_use_api, and optional onboarding.solana (wallet + memo_code for USDC/SOL top-up).
5. If can_use_api is true, use chat/TTS/STT immediately with welcome credits.
6. 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)

1. Login — email OTP or Google (/accounts/login/). New users get welcome + daily free credits.
2. API key — API dashboard → Create key → copy wv_… (shown once).
3. 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

Example agent flow

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

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

Existing account:

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

Credits are billed on your WebVoice account per API call.