Skip to main content
Glama
ghl-mcp-server-v2

ghl-mcp-server-v2

by zackscriven

ghl_media_upload_file

Upload media files to GoHighLevel Media Storage from a local path or hosted URL, with separate size limits for images, documents, and video.

Instructions

multipart/form-data upload. body.file (binary) is required UNLESS body.hosted is true, in which case body.fileUrl is required instead. For local files, pass body.file as { filePath, filename?, mimeType? } — http.ts reads the file from disk and builds a real multipart payload (schema relaxed to allow this 2026-07-16; the earlier note claiming no multipart construction was stale/wrong per http.ts). Max 25MB (images/docs) / 500MB (video). Upload File into Media Storage If hosted is set to true then fileUrl is required. Else file is required. If adding a file, maximum allowed is 25 MB. For video files, the maximum allowed size is 500 MB. Endpoint: POST /medias/upload-file (Version header: v3; source: v3/medias-v3.json) Requires a Sub-Account (location) token. OAuth scopes: medias.write

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "body": "<body>"
    },
    "name": "ghl_media_upload_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body (schema carried verbatim from the official OpenAPI spec).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv2.1.0
    • addedInput schema / properties / body / properties / file / anyOf
      Added value: +[
      +  {
      +    "format": "binary",
      +    "type": "string"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "filePath": {
      +        "type": "string"
      +      },
      +      "filename": {
      +        "type": "string"
      +      },
      +      "mimeType": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "filePath"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedInput schema / properties / body / properties / file / format
      Removed value: -"binary"
    • removedInput schema / properties / body / properties / file / type
      Removed value: -"string"
    • addedInput schema / properties / body / properties / fileUrl / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "filePath": {
      +        "type": "string"
      +      },
      +      "filename": {
      +        "type": "string"
      +      },
      +      "mimeType": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "filePath"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedInput schema / properties / body / properties / fileUrl / type
      Removed value: -"string"
    • addedInput schema / properties / body / properties / hosted / anyOf
      Added value: +[
      +  {
      +    "type": "boolean"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "filePath": {
      +        "type": "string"
      +      },
      +      "filename": {
      +        "type": "string"
      +      },
      +      "mimeType": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "filePath"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedInput schema / properties / body / properties / hosted / type
      Removed value: -"boolean"
    • addedInput schema / properties / body / properties / name / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "filePath": {
      +        "type": "string"
      +      },
      +      "filename": {
      +        "type": "string"
      +      },
      +      "mimeType": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "filePath"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedInput schema / properties / body / properties / name / type
      Removed value: -"string"
    • addedInput schema / properties / body / properties / parentId / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "filePath": {
      +        "type": "string"
      +      },
      +      "filename": {
      +        "type": "string"
      +      },
      +      "mimeType": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "filePath"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedInput schema / properties / body / properties / parentId / type
      Removed value: -"string"
  2. First observedv2.0.0

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds substantive behavior beyond them: hard size ceilings (25MB docs/images, 500MB video), the required location-level token and OAuth scope, and the fact that local paths are read from disk and packaged as real multipart. That last point is valuable, but it is delivered as an internal changelog aside ('the earlier note claiming no multipart construction was stale/wrong per http.ts') that leaks implementation detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Content is duplicated almost verbatim — the file/fileUrl rule appears twice and the 'Upload File into Media Storage' line restates the title. Worse, the description opens with a parenthetical dated changelog note about http.ts that consumes prime front-loaded space with internal maintenance trivia rather than task guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Auth requirements, size ceilings, and the mutually-exclusive input modes make this callable without guessing, and with no output schema the description is not obligated to describe returns. The gap is destination semantics: parentId (target folder) is never explained, so an agent cannot know where the upload lands.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is nominally 100%, so a 3 would be the floor, but the description genuinely adds meaning the schema does not carry: the file-vs-fileUrl conditional gated on hosted, the concrete { filePath, filename?, mimeType? } shape for local uploads, and the size limits that determine which branch is viable. It does not explain parentId at all, which is the one sibling-relevant parameter left ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Upload File into Media Storage') and names the target system concept (media storage). However, it never distinguishes itself from the many other upload-shaped siblings in the list (ghl_kb_upload_file, ghl_conversation_upload_file_attachments, ghl_location_upload_file_custom_fields), so an agent with an ambiguous 'attach a file' request has no routing signal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives conditional call mechanics (hosted=true requires fileUrl, otherwise file) and states the token/scope prerequisite ('Requires a Sub-Account (location) token', 'medias.write'), which is real usage context. But it never says when to pick this tool over ghl_kb_upload_file or ghl_conversation_upload_file_attachments, so the usage boundary is only implied by the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools