deAPI MCP Server

Production-ready Model Context Protocol (MCP) server for the deAPI REST API. This server exposes all deAPI AI capabilities as MCP tools, enabling LLMs to perform audio transcription, image generation, OCR, video generation, text-to-speech, and more.

deAPI v2 — this server targets the deAPI v2 client API (OpenAI-aligned noun paths under /api/v2/*). Set DEAPI_API_VERSION=v1 if you need to point at the legacy v1 endpoints.

Features

• Complete API Coverage: 39 deAPI tools exposed via MCP, covering every v2 client endpoint
• Smart Adaptive Polling: Automatically polls async jobs with optimized intervals based on job type
• OAuth 2.0 Authentication: Secure token exchange via OAuth Authorization Code flow with PKCE
• Error Recovery: Automatic retry logic with exponential backoff
• Progress Reporting: Real-time progress updates to MCP clients
• Type Safety: Full Pydantic schema validation
• Production Ready: Built with FastMCP framework for reliability

Available Tools

Audio Tools

• audio_transcription - Transcribe audio files to text using Whisper models
• audio_transcription_price - Calculate transcription cost
• text_to_audio - Convert text to natural speech (TTS)
• text_to_audio_price - Calculate TTS cost
• text_to_music - Generate music from text description and lyrics
• text_to_music_price - Calculate music generation cost
• audio_url_transcription - Transcribe audio from URLs of completed Twitter Spaces
• audio_url_transcription_price - Calculate Twitter Spaces transcription cost

Video Transcription Tools

• video_file_transcription - Transcribe video files to text
• video_file_transcription_price - Calculate video file transcription cost
• video_url_transcription - Transcribe videos from URLs (YouTube, Twitter/X, Twitch, Kick)
• video_url_transcription_price - Calculate video URL transcription cost

Image Tools

• text_to_image - Generate images from text prompts
• image_to_image - Transform images with text guidance
• image_to_text - Extract text from images (OCR)
• image_remove_background - Remove background from images
• image_upscale - Upscale images to higher resolution
• text_to_image_price - Calculate image generation cost
• image_to_image_price - Calculate image transformation cost
• image_to_text_price - Calculate OCR cost
• image_remove_background_price - Calculate background removal cost
• image_upscale_price - Calculate upscaling cost

Video Tools

• text_to_video - Generate videos from text prompts
• image_to_video - Animate static images into videos
• audio_to_video - Generate video conditioned on audio content
• video_replace - Replace a person in a video with a character from a reference image
• video_remove_background - Remove the background from a video
• video_upscale - Upscale a video to higher resolution
• text_to_video_price - Calculate text-to-video cost
• image_to_video_price - Calculate image-to-video cost
• audio_to_video_price - Calculate audio-to-video cost
• video_replace_price - Calculate video character replacement cost
• video_remove_background_price - Calculate video background-removal cost
• video_upscale_price - Calculate video upscaling cost

Embedding Tools

• text_to_embedding - Generate text embeddings for semantic search
• text_to_embedding_price - Calculate embedding cost

Prompt Tools

• prompt_booster - Enhance a prompt for any deAPI inference type using AI guides (synchronous, returns refined prompt directly)
• prompt_booster_price - Calculate prompt-enhancement cost

Utility Tools

• get_balance - Check account balance
• get_available_models - List available AI models with specifications
• check_job_status - Query async job status by ID

Installation

Prerequisites

For running the MCP server:

• Python 3.10 or higher
• uv, pip, or conda for package management

For a deAPI account:

• Sign up at deapi.ai and get your API token

Setup

1. Clone the repository:

git clone https://github.com/deapi-ai/mcp-server-deapi.git
cd mcp-server-deapi

2. Choose your Python environment setup:

Option A: Using uv (recommended - fastest)

uv pip install -e .

Option B: Using pip

pip install -e .

Option C: Using conda

# Create conda environment
conda create -n mcp-server-deapi python=3.11
conda activate mcp-server-deapi

# Install dependencies
pip install -e .

3. (Optional) Create a .env file for configuration:

# Copy the example file
cp .env.example .env

# Edit with your preferences (optional - defaults work fine)
# DEAPI_API_BASE_URL=https://api.deapi.ai
# DEAPI_HTTP_TIMEOUT=30.0
# DEAPI_MAX_RETRIES=3

Usage

Running the Server

The server can run in two modes:

Local Mode (for use with Claude Desktop on the same machine):

python -m src.server_remote

The server will start on http://localhost:8000 by default.

Remote Mode (for deployment to a remote server):

# Set host to accept external connections
MCP_HOST=0.0.0.0 MCP_PORT=8000 python -m src.server_remote

See the Remote Deployment section for production deployment options.

Connecting from Claude Desktop / Claude.ai

Option 1: Add Connector (Recommended)

Both Claude Desktop and Claude.ai support MCP connectors with built-in OAuth authentication.

1. Get your deAPI token from deapi.ai
2. In Claude Desktop or Claude.ai, go to Settings → Connectors → Add Connector
3. Fill in the connector details:

Name:              deAPI
Remote MCP server: https://your-server-domain:8000/mcp

▼ Advanced settings
OAuth Client ID:     deapi-mcp
OAuth Client Secret: YOUR_DEAPI_TOKEN

4. Click Add — Claude will automatically authenticate via OAuth and discover all tools.

For details on the OAuth flow, see AUTH.md.

Option 2: Config File with Bearer Token (Local Development)

Best for: Server running on the same machine, quick setup without OAuth.

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "deapi": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DEAPI_TOKEN"
      }
    }
  }
}

Replace YOUR_DEAPI_TOKEN with your actual deAPI token. Save the file and restart Claude Desktop.

Using the Tools

Authentication is handled at the connection level, not per-tool-call. Tools do NOT accept a deapi_api_token parameter.

Here's an example workflow:

1. Get available models:

Use get_available_models to see available models

2. Check your balance:

Use get_balance to check remaining credits

3. Generate an image:

Use text_to_image with:
- prompt: "A beautiful sunset over mountains"
- model: "Flux1schnell"

4. Transcribe audio:

Use audio_transcription with:
- audio: "base64-encoded-audio-or-url"
- include_ts: true

Note: When calling tools via Claude Desktop or MCP SDK, authentication is handled automatically through the server connection (OAuth or HTTP headers). See AUTH.md for detailed OAuth setup.

Architecture

Key Components

• DeapiClient (src/deapi_client.py): HTTP client with auth forwarding and retry logic
• PollingManager (src/polling_manager.py): Smart adaptive polling for async jobs
• Schemas (src/schemas.py): Pydantic models for type safety
• Tools (src/tools/): Organized tool implementations
  • audio.py - Audio transcription, TTS & music generation tools
  • image.py - Image generation, transformation, OCR, background removal & upscaling
  • video.py - Video generation, audio-to-video & video replace tools
  • embedding.py - Text embedding tools
  • utility.py - Balance, models, status tools

Smart Adaptive Polling

The server uses job-type-specific polling strategies:

Polling uses exponential backoff with a configurable multiplier (default: 1.5x).

Error Handling

• HTTP Errors: Automatic retry (3 attempts) with exponential backoff
• Timeouts: Graceful handling with clear error messages
• Job Failures: Detected and reported to the client
• API Errors: Properly formatted error responses

Configuration

Configuration can be set via environment variables (prefixed with DEAPI_):

# API Configuration
DEAPI_API_BASE_URL=https://api.deapi.ai
DEAPI_API_VERSION=v2

# HTTP Client
DEAPI_HTTP_TIMEOUT=30.0
DEAPI_MAX_RETRIES=3
DEAPI_RETRY_BACKOFF_FACTOR=2.0

# Polling Configuration (override defaults)
DEAPI_POLLING_AUDIO__INITIAL_DELAY=1.0
DEAPI_POLLING_AUDIO__MAX_DELAY=5.0
DEAPI_POLLING_AUDIO__TIMEOUT=300.0

Development

Project Structure