@t-campbell18/descript-mcp

MCP (Model Context Protocol) server for the Descript API. Enables AI assistants to import media, run AI edits, manage jobs, and more — all through natural language.

Prerequisites

• Node.js >= 18
• A Descript API token (scoped to a Drive)

Installation

npm install -g @t-campbell18/descript-mcp

Or run directly with npx (no install needed):

npx @t-campbell18/descript-mcp --token YOUR_TOKEN

Configuration

Claude Code

claude mcp add descript -- npx @t-campbell18/descript-mcp --token YOUR_TOKEN

Or add to your .claude/settings.json:

{
  "mcpServers": {
    "descript": {
      "command": "npx",
      "args": ["@t-campbell18/descript-mcp", "--token", "YOUR_TOKEN"]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "descript": {
      "command": "npx",
      "args": ["@t-campbell18/descript-mcp", "--token", "YOUR_TOKEN"]
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "descript": {
      "command": "npx",
      "args": ["@t-campbell18/descript-mcp", "--token", "YOUR_TOKEN"]
    }
  }
}

Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "descript": {
      "command": "npx",
      "args": ["@t-campbell18/descript-mcp", "--token", "YOUR_TOKEN"]
    }
  }
}

Environment Variable (all platforms)

Instead of passing --token, you can set the DESCRIPT_API_TOKEN environment variable:

{
  "mcpServers": {
    "descript": {
      "command": "npx",
      "args": ["@t-campbell18/descript-mcp"],
      "env": {
        "DESCRIPT_API_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Tools

| Tool | Description | |------|-------------| | import_media | Import media files into a project and create compositions. Auto-polls until complete. | | run_agent | Execute AI editing via natural language (e.g. "remove filler words"). Auto-polls until complete. | | list_jobs | List recent jobs with optional filters and pagination. | | get_job | Get the status and result of a specific job. | | cancel_job | Cancel a running job. | | check_status | Check API health and validate your token. (WIP) | | create_import_url | Generate a one-time "Edit in Descript" import URL. | | get_published_project | Get metadata and subtitles for a published project. |

CLI Options

| Flag | Description | Default | |------|-------------|---------| | --token <token> | Descript API bearer token | $DESCRIPT_API_TOKEN | | --log-level <level> | Log verbosity: debug, info, warn, error | info |

Features

• Auto-polling: import_media and run_agent poll until jobs complete with exponential backoff (1s, 2s, 4s, 8s, 10s cap). Configurable timeout per call via timeout_ms parameter (default: 5 minutes).
• Rate-limit handling: Automatically retries on HTTP 429 responses using the Retry-After header.
• Input validation: All tool inputs validated with Zod schemas before calling the API.
• Structured errors: API errors are returned with HTTP status codes and details, not raw stack traces.

Development

git clone https://github.com/YOUR_USERNAME/descript-mcp.git
cd descript-mcp
npm install
npm run build
npm test

License

MIT