io.github.deapi-ai/mcp-server-deapi

Official

by deapi-ai · Python

deAPI MCP Server

35 AI tools for image/video generation, TTS, transcription, OCR & embeddings via deAPI

Generate images, videos, transcribe audio, and create embeddings via deAPI.

README.md15 KBView on GitHub

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:

Setup

Clone the repository:

bash

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

Choose your Python environment setup:

Option A: Using uv (recommended - fastest)

bash

uv pip install -e .

Option B: Using pip

bash

pip install -e .

Option C: Using conda

bash

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

# Install dependencies
pip install -e .

(Optional) Create a .env file for configuration:

bash

# 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):

bash

python -m src.server_remote

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

Remote Mode (for deployment to a remote server):

bash

# 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.

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

code

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

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

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

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:

Get available models:

code

Use get_available_models to see available models

Check your balance:

code

Use get_balance to check remaining credits

Generate an image:

code

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

Transcribe audio:

code

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:

Job Type	Initial Delay	Max Delay	Timeout
Audio	1s	5s	5 min
Image	2s	8s	5 min
Video	5s	30s	15 min

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_):

bash

# 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

code

mcp-server-deapi/
├── src/
│   ├── server_remote.py       # Streamable-HTTP MCP server
│   ├── deapi_client.py        # HTTP client with auth forwarding
│   ├── polling_manager.py     # Smart adaptive polling logic
│   ├── schemas.py             # Pydantic models
│   ├── config.py              # Configuration management
│   ├── auth.py                # Authentication middleware
│   ├── fastmcp_auth.py        # FastMCP OAuth provider
│   ├── oauth_endpoints.py     # OAuth 2.0 endpoints
│   └── tools/                 # Tool implementations
│       ├── audio.py           # Audio transcription, TTS & music generation
│       ├── image.py           # Image generation, OCR & processing
│       ├── video.py           # Video generation, audio-to-video & video replace
│       ├── embedding.py       # Text embeddings
│       ├── utility.py         # Balance, models, status
│       └── _price_helpers.py  # Price calculation helpers
├── tests/                     # Test suite
│   ├── __init__.py
│   └── conftest.py           # Pytest fixtures
├── pyproject.toml             # Dependencies
├── Dockerfile                 # Container build
├── docker-compose.yml         # Container orchestration
├── .env.example              # Environment config template
├── README.md                  # This file
├── DEPLOYMENT.md              # Deployment guide
├── AUTH.md                    # OAuth authentication setup
└── CLAUDE.md                  # Claude Code guidance

Running Tests

Install dev dependencies:

bash

uv pip install -e ".[dev]"

Run tests:

bash

pytest

Run smoke tests (requires a running server):

bash

python tests/smoke_test.py

Code Formatting

Format code with Black:

bash

black src/

Lint with Ruff:

bash

ruff check src/

API Token Security

Important: The MCP server does NOT store API tokens. Authentication works as follows:

For Remote HTTP Server: Authentication is handled via OAuth 2.0 (Authorization Code with PKCE) or HTTP headers (Authorization: Bearer token)
Token forwarding: The server forwards authentication to the deAPI API for each request
No persistence: Tokens are used only for the specific request and never persisted or logged
Per-connection auth: Tools do NOT accept deapi_api_token parameters - authentication is managed at the connection level

Always keep your API tokens secure and never commit them to version control. See AUTH.md for detailed OAuth setup.

Remote Deployment

For production environments or when you want to host the MCP server on a remote machine, use the remote server mode.

Quick Start with Docker

Build and run with Docker:

bash

docker build -t mcp-server-deapi .
docker run -d -p 8000:8000 --name mcp-server-deapi mcp-server-deapi

Or use Docker Compose:

bash

docker-compose up -d

Configure Claude Desktop to connect:

json

{
  "mcpServers": {
    "deapi": {
      "url": "http://your-server-ip:8000/mcp"
    }
  }
}

Manual Remote Deployment

On your remote server:

bash

git clone https://github.com/deapi-ai/mcp-server-deapi.git
cd mcp-server-deapi
pip install -e .
python -m src.server_remote

For production with systemd:

bash

# Create /etc/systemd/system/mcp-server-deapi.service
sudo systemctl enable mcp-server-deapi
sudo systemctl start mcp-server-deapi

Behind a reverse proxy (nginx + SSL):

nginx

server {
    listen 443 ssl http2;
    server_name mcp.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400;
    }
}

Cloud Deployment Options

Railway.app: Push to GitHub, connect repository, deploy automatically
Fly.io: fly launch && fly deploy
Heroku: heroku create && git push heroku main
DigitalOcean: Use App Platform or Droplets with Docker
AWS/GCP/Azure: Deploy with container services (ECS, Cloud Run, Container Instances)

For detailed deployment instructions, security considerations, monitoring, and troubleshooting, see DEPLOYMENT.md.

Troubleshooting

Connection Issues

If the server fails to connect:

Check your API token is valid
Verify network connectivity to api.deapi.ai
Check the logs for specific error messages
For remote servers: verify firewall rules and that port 8000 is accessible

Job Timeouts

If jobs are timing out:

Check your balance with get_balance
Verify the job type timeout is appropriate
Use check_job_status to check if the job is still processing

Model Not Found

If you get model errors:

Use get_available_models to see available models
Ensure you're using the correct model name
Check if the model supports your requested operation

Remote Connection Issues

If remote MCP connection fails:

Test the endpoint: curl -N http://your-server:8000/mcp
Check server logs: docker logs mcp-server-deapi or journalctl -u mcp-server-deapi
Verify firewall rules and SSL certificates (if using HTTPS)
Ensure MCP endpoint is accessible from your client

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues related to:

This MCP Server: Open an issue
deAPI Platform: Visit docs.deapi.ai
MCP Protocol: Visit modelcontextprotocol.io

Install

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server-deapi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.deapi.ai/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.