Dreep MCP Server

Give any AI agent a media pipeline.
The official Model Context Protocol server for Dreep: upload, transform, convert, OCR and deliver images, videos and documents from Claude, Cursor, VS Code, Codex, Gemini and every other MCP client.

Dreep docs · API reference · Python SDK · Changelog · Report a bug

Ask your agent things like:

"Upload ~/Desktop/launch/hero.png to marketing/2026 and give me a 1200px WebP and a 400px square thumbnail."

"Pull the text out of this scanned invoice."

"Convert contract.docx to PDF and give me a link that expires in an hour."

"Cut the background out of product.jpg and show it on white."

Contents

• How it works
• Quick start
• Add it to your client: Claude Desktop · Claude Code · Cursor · VS Code · Windsurf · Codex CLI · Gemini CLI · Zed · Cline and others · Remote (HTTP)
• Tools
• Configuration
• Security
• Development

How it works

flowchart LR
    A["AI agent<br/>(Claude, Cursor, Codex...)"] -- "MCP<br/>stdio or HTTP" --> S["dreep-mcp"]
    S -- "dreep SDK<br/>(your API key)" --> API["Dreep API"]
    API --> CDN["Dreep CDN<br/>(or your custom domain)"]
    S -. "URL building:<br/>no network" .-> CDN

1. Your MCP client starts dreep-mcp on your machine (stdio), or connects to one you host (streamable HTTP).
2. The agent sees 14 tools (16 with deletes enabled), each with a typed JSON schema that lists every valid transform value, so it calls them correctly the first time.
3. Each tool calls the official Dreep SDK (Node or Python), which talks to the Dreep API with your key. Delivery and signed URLs are built locally, with no API call.
4. Results come back as structured JSON. Every asset carries the delivery url exactly as Dreep returned it, custom CDN domain included.

There are two native servers, one for Node and one for Python, so you only need the runtime you already have. They expose the same tools: the Python server exports its tool names, descriptions and input schemas to npm/contract/tools.json, the Node server serves that file, and CI fails if it goes stale. The one known difference comes from the Node SDK.

Quick start

1. Create an API key on the API Keys page of the Dreep dashboard.

2. Add the server to your client (below). Pick whichever runtime you already have:

   Runner	Command	Needs
   npx	npx -y dreep-mcp	Node 20+
   uvx	uvx dreep-mcp	uv
   pip	pip install dreep-mcp, then dreep-mcp	Python 3.10+

   The examples below use npx. To use uvx instead, swap "command": "npx", "args": ["-y", "dreep-mcp"] for "command": "uvx", "args": ["dreep-mcp"].

Add it to your client

Every client needs the same three things: a command (npx), its arguments (-y dreep-mcp), and your API key in the DREEP_API_KEY environment variable. Replace drp_live_your_key with your key. Add DREEP_SIGNING_SECRET if you use signed folders, and DREEP_MCP_ALLOW_DELETE if you want the delete tools (see Configuration).

Claude Desktop

Open Settings → Developer → Edit Config, which opens claude_desktop_config.json:

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

{
  "mcpServers": {
    "dreep": {
      "command": "npx",
      "args": ["-y", "dreep-mcp"],
      "env": {
        "DREEP_API_KEY": "drp_live_your_key",
        "DREEP_SIGNING_SECRET": "your_signing_secret"
      }
    }
  }
}

Restart Claude Desktop. Dreep appears under the tools (slider) icon in the message box.

If Claude Desktop can't find npx, use its full path (run which npx). GUI apps don't always inherit your shell's PATH, which is common with nvm.

Claude Code

claude mcp add dreep --scope user -e DREEP_API_KEY=drp_live_your_key -- npx -y dreep-mcp

--scope user makes it available in every project; leave it out to add it to the current project only, or use --scope project to share it with your team through .mcp.json (keep the key out of that file, as shown below). Check it with claude mcp list, or /mcp inside a session.

To share the setup in a repository without committing the key, put this in .mcp.json and let each person export DREEP_API_KEY in their own shell:

{
  "mcpServers": {
    "dreep": {
      "command": "npx",
      "args": ["-y", "dreep-mcp"],
      "env": { "DREEP_API_KEY": "${DREEP_API_KEY}" }
    }
  }
}

Cursor

Open Cursor Settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "dreep": {
      "command": "npx",
      "args": ["-y", "dreep-mcp"],
      "env": { "DREEP_API_KEY": "drp_live_your_key" }
    }
  }
}

The Dreep tools are then available to the agent in chat.

VS Code (GitHub Copilot)

Create .vscode/mcp.json. VS Code asks for the key the first time and stores it securely:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "dreep-api-key",
      "description": "Dreep API key",
      "password": true
    }
  ],
  "servers": {
    "dreep": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "dreep-mcp"],
      "env": { "DREEP_API_KEY": "${input:dreep-api-key}" }
    }
  }
}

Open Copilot Chat in Agent mode and pick the Dreep tools from the tools menu.

Windsurf

Open Windsurf Settings → Cascade → MCP Servers → View raw config, or edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "dreep": {
      "command": "npx",
      "args": ["-y", "dreep-mcp"],
      "env": { "DREEP_API_KEY": "drp_live_your_key" }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.dreep]
command = "npx"
args = ["-y", "dreep-mcp"]
env = { DREEP_API_KEY = "drp_live_your_key" }

Gemini CLI

Add to ~/.gemini/settings.json (or .gemini/settings.json in a project):

{
  "mcpServers": {
    "dreep": {
      "command": "npx",
      "args": ["-y", "dreep-mcp"],
      "env": { "DREEP_API_KEY": "drp_live_your_key" }
    }
  }
}

Zed

Add to Zed's settings.json (Zed → Settings → Open Settings):

{
  "context_servers": {
    "dreep": {
      "command": "npx",
      "args": ["-y", "dreep-mcp"],
      "env": { "DREEP_API_KEY": "drp_live_your_key" }
    }
  }
}

Cline and other clients

Cline (MCP Servers → Configure), Roo Code, Continue, Goose, JetBrains AI Assistant, LM Studio and most other clients take the same mcpServers block shown for Cursor. Anything that can launch a stdio MCP server can run npx -y dreep-mcp with DREEP_API_KEY set.

Remote clients over HTTP

For web-based agents, shared team servers or containers, run the streamable HTTP transport:

export DREEP_API_KEY=drp_live_your_key
export DREEP_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
npx -y dreep-mcp --transport http --host 0.0.0.0 --port 8000

The endpoint is http://<host>:8000/mcp, and every request must send Authorization: Bearer <DREEP_MCP_HTTP_TOKEN>. Put it behind HTTPS (a reverse proxy or your platform's load balancer) before exposing it. Then connect, for example from Claude Code:

claude mcp add --transport http dreep https://mcp.example.com/mcp --header "Authorization: Bearer $DREEP_MCP_HTTP_TOKEN"

Without --host it binds to 127.0.0.1, and it refuses to bind to any other address unless DREEP_MCP_HTTP_TOKEN is set. Over HTTP the tools can't read files on the server unless you allow specific directories with DREEP_MCP_FILE_ROOTS; remote callers send files as content_base64 instead.

Tools

Every tool carries MCP annotations: read-only tools are marked so clients can run them without asking, and delete tools are marked destructive so clients ask you first.

A few behaviours come straight from the API reference, verified against the live API:

• Use URLs as returned. Projects can serve assets from a custom CDN domain, so the tools never construct a delivery URL from scratch; they transform the one Dreep returned.
• Signed URLs sign the asset and expiry only (HMAC-SHA256 over "{id}:{exp}"). Transform parameters ride along unsigned.
• Access control is set on top-level folders; nested folders inherit it. The API has no endpoint for deleting folders.
• Presets need a format, and preset keys may only contain lowercase letters, digits and underscores.

Configuration

Command-line options:

dreep-mcp [--transport {stdio,http}] [--host HOST] [--port PORT] [--path PATH]

Security

• Your API key can read, upload and delete everything in the project. It stays in the server's environment and is sent only to the Dreep API, never to the agent.
• Deletes are off unless you turn them on, and are marked destructive so clients confirm them.
• File access is scoped. Restrict which directories the agent can upload from with DREEP_MCP_FILE_ROOTS. Over HTTP, local file reads are off unless you set it.
• The HTTP transport binds to localhost by default and refuses a public address without DREEP_MCP_HTTP_TOKEN. Tokens are compared in constant time.
• Signed URLs are bearer tokens. Anyone with the link can fetch the asset until it expires.

Report vulnerabilities privately; see SECURITY.md.

Development

git clone https://github.com/IndigoSoftwares21/dreep-mcp.git
cd dreep-mcp
bash scripts/setup_hooks.sh      # venv, dev dependencies, git hooks
bash scripts/quality_gate.sh     # lint, format, repository rules, mypy --strict, Python and Node tests

Try your local checkout in a client by pointing it at the venv: "command": "/path/to/dreep-mcp/.venv/bin/dreep-mcp". To poke at the tools interactively, run the MCP Inspector:

npx @modelcontextprotocol/inspector .venv/bin/dreep-mcp

The layout:

Read CONTRIBUTING.md before opening a pull request, and AGENTS.md if you're an AI agent working in this repository.

License

MIT