{
  "markdown": "# deAPI MCP Server\n\nProduction-ready Model Context Protocol (MCP) server for the [deAPI](https://deapi.ai) 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.\n\n> **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.\n\n## Features\n\n- **Complete API Coverage**: 39 deAPI tools exposed via MCP, covering every v2 client endpoint\n- **Smart Adaptive Polling**: Automatically polls async jobs with optimized intervals based on job type\n- **OAuth 2.0 Authentication**: Secure token exchange via OAuth Authorization Code flow with PKCE\n- **Error Recovery**: Automatic retry logic with exponential backoff\n- **Progress Reporting**: Real-time progress updates to MCP clients\n- **Type Safety**: Full Pydantic schema validation\n- **Production Ready**: Built with FastMCP framework for reliability\n\n## Available Tools\n\n### Audio Tools\n- `audio_transcription` - Transcribe audio files to text using Whisper models\n- `audio_transcription_price` - Calculate transcription cost\n- `text_to_audio` - Convert text to natural speech (TTS)\n- `text_to_audio_price` - Calculate TTS cost\n- `text_to_music` - Generate music from text description and lyrics\n- `text_to_music_price` - Calculate music generation cost\n- `audio_url_transcription` - Transcribe audio from URLs of completed Twitter Spaces\n- `audio_url_transcription_price` - Calculate Twitter Spaces transcription cost\n\n### Video Transcription Tools\n- `video_file_transcription` - Transcribe video files to text\n- `video_file_transcription_price` - Calculate video file transcription cost\n- `video_url_transcription` - Transcribe videos from URLs (YouTube, Twitter/X, Twitch, Kick)\n- `video_url_transcription_price` - Calculate video URL transcription cost\n\n### Image Tools\n- `text_to_image` - Generate images from text prompts\n- `image_to_image` - Transform images with text guidance\n- `image_to_text` - Extract text from images (OCR)\n- `image_remove_background` - Remove background from images\n- `image_upscale` - Upscale images to higher resolution\n- `text_to_image_price` - Calculate image generation cost\n- `image_to_image_price` - Calculate image transformation cost\n- `image_to_text_price` - Calculate OCR cost\n- `image_remove_background_price` - Calculate background removal cost\n- `image_upscale_price` - Calculate upscaling cost\n\n### Video Tools\n- `text_to_video` - Generate videos from text prompts\n- `image_to_video` - Animate static images into videos\n- `audio_to_video` - Generate video conditioned on audio content\n- `video_replace` - Replace a person in a video with a character from a reference image\n- `video_remove_background` - Remove the background from a video\n- `video_upscale` - Upscale a video to higher resolution\n- `text_to_video_price` - Calculate text-to-video cost\n- `image_to_video_price` - Calculate image-to-video cost\n- `audio_to_video_price` - Calculate audio-to-video cost\n- `video_replace_price` - Calculate video character replacement cost\n- `video_remove_background_price` - Calculate video background-removal cost\n- `video_upscale_price` - Calculate video upscaling cost\n\n### Embedding Tools\n- `text_to_embedding` - Generate text embeddings for semantic search\n- `text_to_embedding_price` - Calculate embedding cost\n\n### Prompt Tools\n- `prompt_booster` - Enhance a prompt for any deAPI inference type using AI guides (synchronous, returns refined prompt directly)\n- `prompt_booster_price` - Calculate prompt-enhancement cost\n\n### Utility Tools\n- `get_balance` - Check account balance\n- `get_available_models` - List available AI models with specifications\n- `check_job_status` - Query async job status by ID\n\n## Installation\n\n### Prerequisites\n\n**For running the MCP server:**\n- Python 3.10 or higher\n- `uv`, `pip`, or `conda` for package management\n\n**For a deAPI account:**\n- Sign up at [deapi.ai](https://deapi.ai/settings/api-keys) and get your API token\n\n### Setup\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/deapi-ai/mcp-server-deapi.git\ncd mcp-server-deapi\n```\n\n2. **Choose your Python environment setup:**\n\n**Option A: Using `uv` (recommended - fastest)**\n```bash\nuv pip install -e .\n```\n\n**Option B: Using `pip`**\n```bash\npip install -e .\n```\n\n**Option C: Using `conda`**\n```bash\n# Create conda environment\nconda create -n mcp-server-deapi python=3.11\nconda activate mcp-server-deapi\n\n# Install dependencies\npip install -e .\n```\n\n3. (Optional) Create a `.env` file for configuration:\n```bash\n# Copy the example file\ncp .env.example .env\n\n# Edit with your preferences (optional - defaults work fine)\n# DEAPI_API_BASE_URL=https://api.deapi.ai\n# DEAPI_HTTP_TIMEOUT=30.0\n# DEAPI_MAX_RETRIES=3\n```\n\n## Usage\n\n### Running the Server\n\nThe server can run in two modes:\n\n**Local Mode** (for use with Claude Desktop on the same machine):\n```bash\npython -m src.server_remote\n```\n\nThe server will start on `http://localhost:8000` by default.\n\n**Remote Mode** (for deployment to a remote server):\n```bash\n# Set host to accept external connections\nMCP_HOST=0.0.0.0 MCP_PORT=8000 python -m src.server_remote\n```\n\nSee the [Remote Deployment](#remote-deployment) section for production deployment options.\n\n### Connecting from Claude Desktop / Claude.ai\n\n#### Option 1: Add Connector (Recommended)\n\nBoth Claude Desktop and Claude.ai support MCP connectors with built-in OAuth authentication.\n\n1. Get your deAPI token from [deapi.ai](https://deapi.ai/settings/api-keys)\n2. In Claude Desktop or Claude.ai, go to **Settings → Connectors → Add Connector**\n3. Fill in the connector details:\n\n```\nName:              deAPI\nRemote MCP server: https://your-server-domain:8000/mcp\n\n▼ Advanced settings\nOAuth Client ID:     deapi-mcp\nOAuth Client Secret: YOUR_DEAPI_TOKEN\n```\n\n4. Click **Add** — Claude will automatically authenticate via OAuth and discover all tools.\n\nFor details on the OAuth flow, see [AUTH.md](AUTH.md).\n\n---\n\n#### Option 2: Config File with Bearer Token (Local Development)\n\n**Best for:** Server running on the same machine, quick setup without OAuth.\n\nEdit your Claude Desktop config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"deapi\": {\n      \"url\": \"http://localhost:8000/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_DEAPI_TOKEN\"\n      }\n    }\n  }\n}\n```\n\nReplace `YOUR_DEAPI_TOKEN` with your actual deAPI token. Save the file and restart Claude Desktop.\n\n### Using the Tools\n\n**Authentication is handled at the connection level**, not per-tool-call. Tools do NOT accept a `deapi_api_token` parameter.\n\nHere's an example workflow:\n\n1. **Get available models**:\n```\nUse get_available_models to see available models\n```\n\n2. **Check your balance**:\n```\nUse get_balance to check remaining credits\n```\n\n3. **Generate an image**:\n```\nUse text_to_image with:\n- prompt: \"A beautiful sunset over mountains\"\n- model: \"Flux1schnell\"\n```\n\n4. **Transcribe audio**:\n```\nUse audio_transcription with:\n- audio: \"base64-encoded-audio-or-url\"\n- include_ts: true\n```\n\n**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](AUTH.md) for detailed OAuth setup.\n\n## Architecture\n\n### Key Components\n\n- **DeapiClient** (`src/deapi_client.py`): HTTP client with auth forwarding and retry logic\n- **PollingManager** (`src/polling_manager.py`): Smart adaptive polling for async jobs\n- **Schemas** (`src/schemas.py`): Pydantic models for type safety\n- **Tools** (`src/tools/`): Organized tool implementations\n  - `audio.py` - Audio transcription, TTS & music generation tools\n  - `image.py` - Image generation, transformation, OCR, background removal & upscaling\n  - `video.py` - Video generation, audio-to-video & video replace tools\n  - `embedding.py` - Text embedding tools\n  - `utility.py` - Balance, models, status tools\n\n### Smart Adaptive Polling\n\nThe server uses job-type-specific polling strategies:\n\n| Job Type | Initial Delay | Max Delay | Timeout |\n|----------|--------------|-----------|---------|\n| Audio    | 1s           | 5s        | 5 min   |\n| Image    | 2s           | 8s        | 5 min   |\n| Video    | 5s           | 30s       | 15 min  |\n\nPolling uses exponential backoff with a configurable multiplier (default: 1.5x).\n\n### Error Handling\n\n- **HTTP Errors**: Automatic retry (3 attempts) with exponential backoff\n- **Timeouts**: Graceful handling with clear error messages\n- **Job Failures**: Detected and reported to the client\n- **API Errors**: Properly formatted error responses\n\n## Configuration\n\nConfiguration can be set via environment variables (prefixed with `DEAPI_`):\n\n```bash\n# API Configuration\nDEAPI_API_BASE_URL=https://api.deapi.ai\nDEAPI_API_VERSION=v2\n\n# HTTP Client\nDEAPI_HTTP_TIMEOUT=30.0\nDEAPI_MAX_RETRIES=3\nDEAPI_RETRY_BACKOFF_FACTOR=2.0\n\n# Polling Configuration (override defaults)\nDEAPI_POLLING_AUDIO__INITIAL_DELAY=1.0\nDEAPI_POLLING_AUDIO__MAX_DELAY=5.0\nDEAPI_POLLING_AUDIO__TIMEOUT=300.0\n```\n\n## Development\n\n### Project Structure\n\n```\nmcp-server-deapi/\n├── src/\n│   ├── server_remote.py       # Streamable-HTTP MCP server\n│   ├── deapi_client.py        # HTTP client with auth forwarding\n│   ├── polling_manager.py     # Smart adaptive polling logic\n│   ├── schemas.py             # Pydantic models\n│   ├── config.py              # Configuration management\n│   ├── auth.py                # Authentication middleware\n│   ├── fastmcp_auth.py        # FastMCP OAuth provider\n│   ├── oauth_endpoints.py     # OAuth 2.0 endpoints\n│   └── tools/                 # Tool implementations\n│       ├── audio.py           # Audio transcription, TTS & music generation\n│       ├── image.py           # Image generation, OCR & processing\n│       ├── video.py           # Video generation, audio-to-video & video replace\n│       ├── embedding.py       # Text embeddings\n│       ├── utility.py         # Balance, models, status\n│       └── _price_helpers.py  # Price calculation helpers\n├── tests/                     # Test suite\n│   ├── __init__.py\n│   └── conftest.py           # Pytest fixtures\n├── pyproject.toml             # Dependencies\n├── Dockerfile                 # Container build\n├── docker-compose.yml         # Container orchestration\n├── .env.example              # Environment config template\n├── README.md                  # This file\n├── DEPLOYMENT.md              # Deployment guide\n├── AUTH.md                    # OAuth authentication setup\n└── CLAUDE.md                  # Claude Code guidance\n```\n\n### Running Tests\n\nInstall dev dependencies:\n```bash\nuv pip install -e \".[dev]\"\n```\n\nRun tests:\n```bash\npytest\n```\n\nRun smoke tests (requires a running server):\n```bash\npython tests/smoke_test.py\n```\n\n### Code Formatting\n\nFormat code with Black:\n```bash\nblack src/\n```\n\nLint with Ruff:\n```bash\nruff check src/\n```\n\n## API Token Security\n\n**Important**: The MCP server does NOT store API tokens. Authentication works as follows:\n\n1. **For Remote HTTP Server**: Authentication is handled via OAuth 2.0 (Authorization Code with PKCE) or HTTP headers (Authorization: Bearer token)\n2. **Token forwarding**: The server forwards authentication to the deAPI API for each request\n3. **No persistence**: Tokens are used only for the specific request and never persisted or logged\n4. **Per-connection auth**: Tools do NOT accept `deapi_api_token` parameters - authentication is managed at the connection level\n\nAlways keep your API tokens secure and never commit them to version control. See [AUTH.md](AUTH.md) for detailed OAuth setup.\n\n## Remote Deployment\n\nFor production environments or when you want to host the MCP server on a remote machine, use the remote server mode.\n\n### Quick Start with Docker\n\n1. **Build and run with Docker:**\n```bash\ndocker build -t mcp-server-deapi .\ndocker run -d -p 8000:8000 --name mcp-server-deapi mcp-server-deapi\n```\n\n2. **Or use Docker Compose:**\n```bash\ndocker-compose up -d\n```\n\n3. **Configure Claude Desktop to connect:**\n```json\n{\n  \"mcpServers\": {\n    \"deapi\": {\n      \"url\": \"http://your-server-ip:8000/mcp\"\n    }\n  }\n}\n```\n\n### Manual Remote Deployment\n\n1. **On your remote server:**\n```bash\ngit clone https://github.com/deapi-ai/mcp-server-deapi.git\ncd mcp-server-deapi\npip install -e .\npython -m src.server_remote\n```\n\n2. **For production with systemd:**\n```bash\n# Create /etc/systemd/system/mcp-server-deapi.service\nsudo systemctl enable mcp-server-deapi\nsudo systemctl start mcp-server-deapi\n```\n\n3. **Behind a reverse proxy (nginx + SSL):**\n```nginx\nserver {\n    listen 443 ssl http2;\n    server_name mcp.yourdomain.com;\n\n    ssl_certificate /path/to/cert.pem;\n    ssl_certificate_key /path/to/key.pem;\n\n    location / {\n        proxy_pass http://localhost:8000;\n        proxy_http_version 1.1;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"upgrade\";\n        proxy_buffering off;\n        proxy_cache off;\n        proxy_read_timeout 86400;\n    }\n}\n```\n\n### Cloud Deployment Options\n\n- **Railway.app**: Push to GitHub, connect repository, deploy automatically\n- **Fly.io**: `fly launch && fly deploy`\n- **Heroku**: `heroku create && git push heroku main`\n- **DigitalOcean**: Use App Platform or Droplets with Docker\n- **AWS/GCP/Azure**: Deploy with container services (ECS, Cloud Run, Container Instances)\n\nFor detailed deployment instructions, security considerations, monitoring, and troubleshooting, see [DEPLOYMENT.md](DEPLOYMENT.md).\n\n## Troubleshooting\n\n### Connection Issues\n\nIf the server fails to connect:\n1. Check your API token is valid\n2. Verify network connectivity to api.deapi.ai\n3. Check the logs for specific error messages\n4. For remote servers: verify firewall rules and that port 8000 is accessible\n\n### Job Timeouts\n\nIf jobs are timing out:\n1. Check your balance with `get_balance`\n2. Verify the job type timeout is appropriate\n3. Use `check_job_status` to check if the job is still processing\n\n### Model Not Found\n\nIf you get model errors:\n1. Use `get_available_models` to see available models\n2. Ensure you're using the correct model name\n3. Check if the model supports your requested operation\n\n### Remote Connection Issues\n\nIf remote MCP connection fails:\n1. Test the endpoint: `curl -N http://your-server:8000/mcp`\n2. Check server logs: `docker logs mcp-server-deapi` or `journalctl -u mcp-server-deapi`\n3. Verify firewall rules and SSL certificates (if using HTTPS)\n4. Ensure MCP endpoint is accessible from your client\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor issues related to:\n- **This MCP Server**: [Open an issue](https://github.com/deapi-ai/mcp-server-deapi/issues)\n- **deAPI Platform**: Visit [docs.deapi.ai](https://docs.deapi.ai/)\n- **MCP Protocol**: Visit [modelcontextprotocol.io](https://modelcontextprotocol.io)\n<!-- mcp-name: io.github.deapi-ai/mcp-server-deapi -->\n",
  "bytes": 15121,
  "sha": "63673f88998277aebaf993bd304f62bc783c3a75b81be32cf51e4b5b4e45b862",
  "repo_slug": "deapi-ai/mcp-server-deapi",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_deapi_ai_mcp_server_deapi_643dfae9/readme"
}