# uploads.sh (npm · @buildinternet/uploads)

Host files from coding agents; stage on a branch and attach to GitHub PRs.

- Trust score: 92/100 (high trust)
- Change this week: +4
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-09-20

## Components

- remote · `agents.uploads.sh`: 38/100, [markdown](https://verifymcp.io/servers/sh-uploads-mcp/agents.md), [page](https://verifymcp.io/servers/sh-uploads-mcp/agents)
- npm · `@buildinternet/uploads`: 92/100 (this document), [markdown](https://verifymcp.io/servers/sh-uploads-mcp/buildinternet-uploads.md), [page](https://verifymcp.io/servers/sh-uploads-mcp/buildinternet-uploads)

## Channel facts

- Registry: `npm`
- Package: `@buildinternet/uploads`
- Version: `0.54.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-09-20.

- **Supply Chain Security**: 99/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 5 of 45 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to buildinternet/uploads).
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 2 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 72/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 5092 tokens (~212/item across 24 items; 24 tools + 0 resources), over budget; trim descriptions and params.
  - Tools include usage examples.
- **Stability & Change Management**: 83/100
  - Stability observed for 25 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (83% of tools); any adoption earns full credit.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - All 3 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation.
  - An AI judge read all 24 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

## Install

### How do I install the uploads.sh MCP server?

uploads.sh runs locally as an npm package, launched with npx -y @buildinternet/uploads. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add sh-uploads-mcp -- npx -y @buildinternet/uploads
```

### Cursor

```json
{
  "mcpServers": {
    "sh-uploads-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@buildinternet/uploads"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "sh-uploads-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@buildinternet/uploads"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add sh-uploads-mcp -- npx -y @buildinternet/uploads
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sh-uploads-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@buildinternet/uploads"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add sh-uploads-mcp --command npx --arg -y --arg @buildinternet/uploads
```

### Hermes

```yaml
mcp_servers:
  sh-uploads-mcp:
    command: "npx"
    args: ["-y", "@buildinternet/uploads"]
```

### Netclaw

```json
{
  "McpServers": {
    "sh-uploads-mcp": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "@buildinternet/uploads"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add sh-uploads-mcp -t stdio -c npx -a -y @buildinternet/uploads
```

### Other

```json
{
  "mcpServers": {
    "sh-uploads-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@buildinternet/uploads"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-09-20 (score 92, +1)

No change was recorded against any check on this day. Stability & Change Management went from 80 to 83. That category is still filling its 30-day observation window: 24 days of observed history at the previous scan, 25 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-18 (score 91, +1)

No change was recorded against any check on this day. Stability & Change Management went from 73 to 77. That category is still filling its 30-day observation window: 22 days of observed history at the previous scan, 23 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-16 (score 90, +1)

No change was recorded against any check on this day. Stability & Change Management went from 67 to 70. That category is still filling its 30-day observation window: 20 days of observed history at the previous scan, 21 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-15 (score 89, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-09-14 (score 74, −14)

- [security regression] Malware scan: pass → unverified
- [security regression] Tool safety: pass → unverified
- [security regression] Stability: 0.60 → unverified
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional] First check of Schema quality: unverified
- [functional] Package version: 0.52.1 → 0.54.0

### 2026-09-12 (score 88, +1)

No change was recorded against any check on this day. Stability & Change Management went from 53 to 57. That category is still filling its 30-day observation window: 16 days of observed history at the previous scan, 17 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-09 (score 87, +1)

No change was recorded against any check on this day. Stability & Change Management went from 43 to 47. That category is still filling its 30-day observation window: 13 days of observed history at the previous scan, 14 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-07 (score 86, +1)

No change was recorded against any check on this day. Stability & Change Management went from 37 to 40. That category is still filling its 30-day observation window: 11 days of observed history at the previous scan, 12 at this one. The score rises as the window fills, whether or not the server changes.

## MCP tools (24)

### `gallery_create` (~87 tokens)

Create gallery

Create a public ordered media gallery in the workspace. The returned canonical URL is safe to give users, but anyone who knows it can view the gallery and its media.

Input parameters:

- `description` (string): Optional public gallery description.
- `title` (string, required): Gallery title (1–120 characters).
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `coverItemId` (string|null)
- `createdAt` (string)
- `description` (string|null)
- `id` (string)
- `itemCount` (number)
- `items` (array)
- `references` (array)
- `title` (string)
- `updatedAt` (string)
- `url` (string)
- `version` (number)
- `visibility` (string)
- `workspace` (string)

### `gallery_get` (~66 tokens)

Get gallery

Get a workspace-owned gallery, including ordered media and its canonical public URL. Gallery media is public to anyone with the URL.

Input parameters:

- `galleryId` (string, required): Opaque gallery ID.
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `coverItemId` (string|null)
- `createdAt` (string)
- `description` (string|null)
- `id` (string)
- `itemCount` (number)
- `items` (array)
- `references` (array)
- `title` (string)
- `updatedAt` (string)
- `url` (string)
- `version` (number)
- `visibility` (string)
- `workspace` (string)

### `gallery_add` (~114 tokens)

Add gallery item

Add one existing, publicly served workspace object to a gallery. Reads the latest gallery version before writing, so the optimistic API version is handled safely. Does not upload or delete the object.

Input parameters:

- `altText` (string): Optional public alt text.
- `caption` (string): Optional public caption.
- `galleryId` (string, required): Opaque gallery ID.
- `objectKey` (string, required): Existing public object key to add.
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `altText` (string|null)
- `caption` (string|null)
- `contentType` (string|null)
- `createdAt` (string)
- `embedUrl` (string|null)
- `filename` (string)
- `id` (string)
- `modified` (string|null)
- `objectKey` (string)
- `pageUrl` (string)
- `position` (number)
- `posterUrl` (string)
- `size` (number|null)
- `status` (string)
- `uploaded` (string|null)
- `url` (string|null)
- `videoDimensions` (object)

### `gallery_link` (~107 tokens)

Link gallery

Link a gallery to an external reference. References use provider-neutral fields; github currently accepts owner/repo#number or a strict GitHub issue/PR URL. No GitHub credentials or API calls are used.

Input parameters:

- `coordinate` (string, required): Provider-native external reference coordinate.
- `galleryId` (string, required): Opaque gallery ID.
- `provider` (string, required): External provider (currently github).
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `canonicalUrl` (string|null)
- `coordinate` (string)
- `createdAt` (string)
- `id` (string)
- `kind` (string)
- `provider` (string)
- `resourceType` (string)
- `title` (string)

### `gallery_find_by_reference` (~106 tokens)

Find galleries

Find workspace galleries linked to an external reference. Returns gallery summaries and canonical public URLs without contacting the provider.

Input parameters:

- `coordinate` (string, required): Provider-native external reference coordinate.
- `cursor` (string): Pagination cursor from a previous response.
- `limit` (number): Page size (default 50, max 100).
- `provider` (string, required): External provider (currently github).
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `galleries` (array)
- `nextCursor` (string|null)

### `put` (~1118 tokens)

Upload file

Upload one or more files and get a public URL plus GitHub-ready markdown. Prefer `embedUrl` in GitHub markdown. Pass `contentUrl` for a public HTTPS file, or http://localhost on this machine, instead of a local path. With `pr`/`issue`, keys are stable and the managed comment is synced. All uploads are public. Accepts images (PNG, JPEG, GIF, WebP, AVIF), video (MP4, WebM, MOV), PDF, zip, gzip, and text (plain, markdown, CSV, JSON). SVG and XML are accepted only on storage lanes verified to serve them sandboxed (see the workspace's storage settings); HTML is rejected.

Input parameters:

- `alt` (string): Alt text for the markdown (default: each file's name; with multiple files applies to all).
- `app` (string): Which surface is shown: web, ios, android, cli. Worth setting only when the same route exists on more than one surface.
- `comment` (boolean): With `pr`/`issue` (or an auto-detected PR): create or update the managed attachments comment. Best-effort.
- `contentBase64` (string): Base64-encoded file content for in-memory uploads; requires filename.
- `contentType` (string): Override the Content-Type (ignored when optimize rewrites the body).
- `contentUrl` (string): URL to fetch and upload. Public HTTPS, or http://localhost / 127.0.0.1 / *.localhost on this machine. Filename is optional when the URL path has a leaf. Other private/internal hosts are rejected. Exa…
- `destination` (string): Typed destination root: screenshots | gh | f. Sets the key prefix; first-class alternative to prefix. With pr/issue must be gh or omitted.
- `dryRun` (boolean): Resolve key + public URL without uploading (also previews a strict-key refusal via wouldRefuse). Not with comment.
- `file` (string): Path of a single file to upload. Exactly one of file, files, contentBase64, or contentUrl is required.
- `filename` (string): Filename for contentBase64/contentUrl (drives the key and content type). With single `file`, overrides the key's leaf (clean name) while keeping the pr/default path.
- `files` (array): Paths of multiple files to upload in parallel. Returns { uploads, failures }. Cannot combine with file, contentBase64, contentUrl, key, or filename.
- `frame` (string): Optional frame before optimize: phone | browser | iphone-16-pro.
- `frameFit` (string): cover (default) or contain.
- `frameUrl` (string): Address bar text for frame=browser.
- `issue` (number): Attach to this issue. Mutually exclusive with pr.
- `keepExif` (boolean): Keep EXIF/XMP/ICC when optimizing (default: strip for privacy on public embeds).
- `key` (string): Override the object key. Single file only; cannot combine with `pr`/`issue`.
- `metadata` (object): Queryable tags for later search (key→value). Use `path` for the route (e.g. /settings), not route/page/screen. Omit to leave existing tags; pass an object (even {}) to replace them. `state` and `app`…
- `noGit` (boolean): Don't derive the repo segment from git.
- `noOptimize` (boolean): Skip client-side image optimization (default: optimize still images to WebP).
- `noPr` (boolean): Skip auto-PR context (issue #700): without pr/issue/key/ref/prefix/destination, a call on a branch mapping to exactly one open PR otherwise behaves as if pr had been passed (stable key + managed comm…
- `optimizeMaxEdge` (number): Max long edge in pixels when optimizing (default: 2400).
- `optimizeQuality` (number): WebP quality 1–100 when optimizing (default: 85).
- `pr` (number): Attach to this pull request. Mutually exclusive with issue.
- `prefix` (string): Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX). Cannot be combined with pr/issue.
- `ref` (string): PR/issue/branch key segment (default: today, or UPLOADS_DEFAULT_REF). Cannot be combined with pr/issue.
- `replace` (boolean): Overwrite an existing object on a non-`gh/` key. Default false (or true if UPLOADS_OVERWRITE=1). No effect on `pr`/`issue` keys, which always overwrite.
- `repo` (string): owner/name repo segment (default: git remote, or UPLOADS_DEFAULT_REPO).
- `state` (string): The UI state this image shows. Set it whenever the image is one side of a comparison — before/after is the most useful pair in a PR, and is what makes `find_files` with state=after work later.
- `width` (number): Emit <img width=…> markdown instead of a plain image embed.
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `comment` (object)
- `commentError` (string)
- `contentType` (string)
- `dryRun` (boolean)
- `embedUrl` (string|null)
- `failures` (array)
- `file` (string)
- `frame` (object)
- `hint` (string)
- `key` (string)
- `markdown` (string)
- `metadata` (object)
- `optimize` (object)
- `promoteError` (string)
- `promotion` (object)
- `provenance` (object)
- `replaced` (boolean)
- `size` (number)
- `uploads` (array)
- `url` (string|null)
- `visibility` (string)
- `workspace` (string)

### `screenshot` (~1085 tokens)

Capture screenshot

Capture a URL or local HTML file and host it. Shares put's attach, comment, and metadata options. `via=local` needs Chrome; `via=remote` renders server-side. localhost URLs are local-only.

Input parameters:

- `alt` (string): Alt text for the markdown (default: derived filename).
- `app` (string): Which surface is shown: web, ios, android, cli. Worth setting only when the same route exists on more than one surface.
- `browser` (string): Explicit local browser executable path (local backend only).
- `cdp` (string): Attach to a running Chrome via CDP instead of launching one (local backend only).
- `colorScheme` (string): Emulate prefers-color-scheme: dark | light. Full media-query emulation requires via: "local" — the remote backend only sets the CSS color-scheme property and won't flip a page's own prefers-color-sch…
- `comment` (boolean): With pr/issue (or auto-detected PR context): create/update the managed attachments comment (best-effort).
- `destination` (string): Typed destination root: screenshots | gh | f. With pr/issue must be gh or omitted.
- `dryRun` (boolean): Capture + resolve key/URL without uploading. Not with comment or galleryId.
- `frame` (string): Optional frame before optimize: phone | browser | iphone-16-pro.
- `frameFit` (string): cover (default) or contain.
- `frameUrl` (string): Address bar text for frame=browser.
- `fullPage` (boolean): Capture the full scrollable page.
- `galleryId` (string): Add the uploaded object to this public gallery.
- `hide` (array): CSS selectors to hide (display:none) before capture. Works on both backends.
- `issue` (number): Attach to this issue. Mutually exclusive with pr.
- `keepExif` (boolean): Keep EXIF/XMP/ICC when optimizing.
- `key` (string): Explicit object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.png). Cannot be combined with pr/issue.
- `maxHeight` (number): Cap on full-page capture height in CSS px (default: 5000, 0 = uncapped). A page over the cap is clipped, with a `hint` in the result. Requires fullPage. Applied on both via: local and via: remote so…
- `metadata` (object): Queryable tags for later search (key→value). Use `path` for the route (e.g. /settings), not route/page/screen. Omit to leave existing tags; pass an object (even {}) to replace them. `state` and `app`…
- `noGit` (boolean): Don't derive the repo segment from git.
- `noHideDevTools` (boolean): Don't auto-hide framework dev toolbars (Astro/Next/Nuxt/Vite), which are hidden by default for localhost/private-network targets.
- `noOptimize` (boolean): Skip client-side image optimization (default: optimize to WebP).
- `noPr` (boolean): Skip auto-PR context (issue #700): without pr/issue/key/ref/prefix/destination, a call on a branch mapping to exactly one open PR otherwise behaves as if pr had been passed. Also opts out via UPLOADS…
- `optimizeMaxEdge` (number): Max long edge in pixels when optimizing.
- `optimizeQuality` (number): WebP quality 1-100 when optimizing.
- `pr` (number): Attach to this pull request. Mutually exclusive with issue.
- `prefix` (string): Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX).
- `reducedMotion` (boolean): Emulate prefers-reduced-motion: reduce so animations settle. Best-effort on via: "remote" (neutralizes animations via injected CSS).
- `ref` (string): PR/issue/branch key segment (default: today, or UPLOADS_DEFAULT_REF).
- `repo` (string): owner/name repo segment (default: git remote, or UPLOADS_DEFAULT_REPO).
- `selector` (string): Capture one element instead of the viewport.
- `state` (string): The UI state this image shows. Set it whenever the image is one side of a comparison — before/after is the most useful pair in a PR, and is what makes `find_files` with state=after work later.
- `target` (string, required): http(s) URL, or a path to a local .html file.
- `via` (string): Capture backend: auto (default) | local | remote.
- `viewport` (string): WIDTHxHEIGHT[@SCALEx], e.g. 1280x800@2x (default: 1280x800@2).
- `wait` (string): Settle strategy: load (default) | domcontentloaded | networkidle | a millisecond count (millisecond counts are local-only — via: "local").
- `width` (number): Emit <img width=…> markdown instead of a plain embed.
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

### `attach` (~604 tokens)

Attach to GitHub

Upload one or more files as stable PR/issue attachments (in parallel) and maintain a managed GitHub comment. Returns `uploads` and `failures` (one bad file does not abort the batch). Each success has `url`, `embedUrl`, and `markdown` (prefer embedUrl for GitHub). With no pr/issue, targets the current branch PR, and files already staged for that branch are promoted into it (`promotion`/`promoteError`; renamed branches are followed automatically, or name the old branch with fromBranch). Attachments are public and keys are predictable; upload only non-sensitive media.

Input parameters:

- `app` (string): Which surface is shown: web, ios, android, cli. Worth setting only when the same route exists on more than one surface.
- `contentType` (string): Override the Content-Type (applied to every file; ignored when optimize rewrites).
- `files` (array, required): Paths of the files to upload (at least one).
- `frame` (string): Optional frame before optimize: phone | browser | iphone-16-pro.
- `frameFit` (string): cover (default) or contain.
- `frameUrl` (string): Address bar text for frame=browser.
- `fromBranch` (string): Promote files staged under this branch name instead of the current branch (for a branch renamed before the PR opened).
- `issue` (number): Attach to this issue. Mutually exclusive with pr.
- `keepExif` (boolean): Keep EXIF/XMP/ICC when optimizing (default: strip for privacy on public embeds).
- `metadata` (object): Queryable tags for later search (key→value). Use `path` for the route (e.g. /settings), not route/page/screen. Omit to leave existing tags; pass an object (even {}) to replace them. `state` and `app`…
- `noComment` (boolean): Upload only; don't create/update the managed comment.
- `noOptimize` (boolean): Skip client-side image optimization (default: optimize still images to WebP).
- `noPromote` (boolean): Skip promoting files staged for the current branch into the PR.
- `optimizeMaxEdge` (number): Max long edge in pixels when optimizing (default: 2400).
- `optimizeQuality` (number): WebP quality 1–100 when optimizing (default: 85).
- `pr` (number): Attach to this pull request. Mutually exclusive with issue.
- `repo` (string): owner/name repository (default: gh/git inference).
- `state` (string): The UI state this image shows. Set it whenever the image is one side of a comparison — before/after is the most useful pair in a PR, and is what makes `find_files` with state=after work later.
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

### `list` (~178 tokens)

List files

List uploaded objects in the workspace, filtered by key prefix or by a PR/issue's attachments. Paginate with cursor, or set all to fetch every page.

Input parameters:

- `all` (boolean): Follow cursors and return every page.
- `cursor` (string): Pagination cursor from a previous call.
- `issue` (number): List attachments for this issue. Mutually exclusive with pr.
- `limit` (number): Page size.
- `pr` (number): List attachments for this pull request. Mutually exclusive with issue.
- `prefix` (string): Key prefix filter (default: UPLOADS_DEFAULT_PREFIX + '/'). Cannot be combined with pr/issue.
- `repo` (string): owner/name repository (default: gh/git inference).
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `cursor` (string|null)
- `items` (array)
- `prefixes` (array)

### `staged` (~94 tokens)

List staged files

List files staged for a git branch and whether they will auto-attach when a PR opens. Returns `{ repo, branch, files, binding }`.

Input parameters:

- `branch` (string): Branch name (default: current git branch, worktree-safe).
- `repo` (string): owner/name repo (default: gh/git remote inference).
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

### `delete` (~69 tokens)

Delete file

Delete an uploaded object by key. Set dryRun to preview without deleting.

Input parameters:

- `dryRun` (boolean): Report what would be deleted without deleting.
- `key` (string, required): Object key to delete.
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `deleted` (boolean)
- `dryRun` (boolean)
- `key` (string)

### `get_metadata` (~66 tokens)

Get metadata

Read the queryable tags on one file. Returns `{ metadata }` (empty when none). Same as `uploads meta get`.

Input parameters:

- `key` (string, required): Object key to inspect.
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `metadata` (object)

### `set_metadata` (~122 tokens)

Set metadata

Set or delete queryable tags on an existing file. `set` wins over `delete` for the same key. Requires `set` and/or `delete`. Same as `uploads meta set`.

Input parameters:

- `delete` (array): Keys to remove.
- `key` (string, required): Object key to update.
- `set` (object): Keys to set or overwrite. Use `path` for the route (e.g. /settings), not route/page/screen.
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `metadata` (object)

### `find_files` (~248 tokens)

Find files

Search files by metadata (`filters`) and/or filename substring (`name`). At least one is required. Same as `uploads find`.

Input parameters:

- `all` (boolean): Follow the cursor and return every page, up to a bounded number of requests. A non-null `cursor` in the result means that bound was reached before the end — pass it back to continue.
- `cursor` (string): Opaque continuation from a previous call's `cursor`. Pass it back unchanged with the same filters/name to get the next page; a null `cursor` means there are no more pages.
- `filters` (object): Equality filters; all must match. Use `path` for the route (e.g. /settings), not route/page/screen. Optional when `name` is set.
- `limit` (number): Page size (default 50, max 500).
- `name` (string): Case-insensitive substring match on object keys (1–128 chars). Optional when `filters` is non-empty.
- `prefix` (string): Key prefix filter, combinable with filters/name.
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `cursor` (string|null)
- `items` (array)
- `truncated` (boolean)

### `list_metadata_keys` (~91 tokens)

List metadata keys

List metadata keys in the workspace (with counts). Pass `key` to list that key's values instead. Use before `find_files`. Same as `uploads meta keys`.

Input parameters:

- `key` (string): When set, return distinct values for this metadata key (with counts) instead of the key list.
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `key` (string)
- `keys` (array)
- `truncated` (boolean)
- `values` (array)

### `usage` (~50 tokens)

Show usage

Workspace storage and monthly upload counters (and remaining headroom when budgets are configured). Same as `uploads usage`.

Input parameters:

- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `bytes` (number)
- `maxStorageBytes` (number)
- `maxUploadsPerPeriod` (number)
- `objects` (number)
- `periodStart` (string)
- `plan` (string)
- `scopes` (array)
- `sharedBytes` (number)
- `sharedObjects` (number)
- `storage` (object)
- `storageBudgetBasis` (string)
- `storageRemainingBytes` (number)
- `updatedAt` (string)
- `uploadsInPeriod` (number)
- `uploadsRemaining` (number)
- `workspace` (string)

### `reconcile` (~60 tokens)

Reconcile usage

Rebuild usage ledger bytes/objects from storage (source of truth). Preserves the monthly upload counter. Requires files:write. Same as `uploads reconcile`.

Input parameters:

- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `bytes` (number)
- `changed` (boolean)
- `objects` (number)
- `previous` (object)
- `unprefixedBucket` (boolean)
- `usage` (object)
- `workspace` (string)

### `purge_expired` (~63 tokens)

Purge expired files

Delete objects older than the workspace retentionDays setting, then reconcile. Skips if retention is unset. Requires files:delete. Same as `uploads purge-expired`.

Input parameters:

- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `cutoff` (string)
- `deleted` (number)
- `freedBytes` (number)
- `keys` (array)
- `keysTruncated` (boolean)
- `reason` (string)
- `reconcile` (object)
- `retentionDays` (number)
- `skipped` (boolean)
- `workspace` (string)

### `comment` (~138 tokens)

Sync attachments comment

Create or update the managed attachments comment on a GitHub PR or issue, listing everything uploaded for it. Posts as uploads-sh[bot] when the GitHub App is installed on the repo; otherwise via local gh auth. Edits its own prior comment in place and never touches other comments.

Input parameters:

- `issue` (number): Comment on this issue. Mutually exclusive with pr.
- `pr` (number): Comment on this pull request. Mutually exclusive with issue.
- `repo` (string): owner/name repository (default: gh/git inference).
- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

Output parameters:

- `action` (string)
- `commentUrl` (string)
- `count` (number)
- `fixUrl` (string)
- `kind` (string)
- `message` (string)
- `num` (number)
- `posted` (boolean)
- `reason` (string)
- `repo` (string)
- `required` (array)
- `via` (string)

### `search_docs` (~217 tokens)

Search uploads.sh docs

Search the public uploads.sh documentation. Use this to answer questions about uploads.sh product workflows, including: attaching screenshots and video to GitHub PRs and issues; staging files before a PR exists; galleries; the GitHub App; comment config (.uploads.yml); hosted MCP and agent setup; screenshot capture and annotate; plans and limits; bring-your-own bucket. Same as `uploads docs`. Returns titles, URLs, and snippets. Pass `page` to fetch the full markdown of one page (slug, path, or URL). Omit `query` to list the catalog.

Input parameters:

- `limit` (number): How many search hits to return (default 5, max 50). Ignored when fetching one page.
- `page` (string): Fetch one page as markdown. Accepts a slug (`attach`), path (`/docs/agents`), or https://uploads.sh URL.
- `query` (string): Search query (e.g. 'stage before a PR'). A single slug like 'attach' fetches that page.

Output parameters:

- `query` (string)
- `results` (array)
- `total` (number)
- `url` (string)

### `changelog` (~85 tokens)

Product changelog

Read recent uploads.sh product updates (platform and CLI). Returns the latest entries with titles, dates, summaries, and a link to the full changelog at https://uploads.sh/changelog. Same as `uploads changelog`. Use this to discover new features before recommending uploads.sh workflows.

Input parameters:

- `limit` (number): How many entries to return (default 5, max 50).

Output parameters:

- `entries` (array)
- `feed` (string)
- `url` (string)

### `whoami` (~54 tokens)

Who am I

Show the active uploads.sh identity: workspace, API URL, and token scopes. Use this to learn which workspace you're talking to. A successful result also means the API is up. For a full setup diagnosis, use `doctor`.

Output parameters:

- `apiUrl` (string)
- `ok` (boolean)
- `scopes` (array)
- `signedIn` (boolean)
- `userId` (string|null)
- `workspace` (string)

### `doctor` (~57 tokens)

Diagnose setup

Diagnose the configuration: API health, token auth, and workspace/token alignment. Returns the same report as `uploads doctor --json`, including hints.

Input parameters:

- `workspace` (string): Override the workspace for this call (like the CLI's --workspace flag).

### `report` (~213 tokens)

Send diagnostic report

Send an explicit diagnostic report to the uploads team (message + optional text log). Only call this when the user asked to submit feedback, a bug report, or error logs — never automatically. Do not include tokens, secrets, or private file contents. Same as `uploads report`.

Input parameters:

- `attachmentFilename` (string): Filename label for attachmentText (default: trace.txt).
- `attachmentText` (string): Optional text log/trace body the user consented to send (max 256 KiB). Not a file path.
- `command` (string): Command that failed (e.g. put) — name only, no paths or args.
- `contact` (string): Optional contact for follow-up (email or handle).
- `errorCode` (string): Optional UploadsError code (e.g. KEY_POLICY).
- `message` (string, required): Short description of the problem (required, 5–4000 chars).
- `type` (string): One of: bug, error, idea, other (default: other).

Output parameters:

- `hasAttachment` (boolean)
- `id` (string)
- `ok` (boolean)

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/sh-uploads-mcp/buildinternet-uploads#diagnostics

## Score history

- 2026-09-20: 92
- 2026-09-19: 91
- 2026-09-18: 91
- 2026-09-17: 90
- 2026-09-16: 90
- 2026-09-15: 89
- 2026-09-14: 74
- 2026-09-13: 88
- 2026-09-12: 88
- 2026-09-11: 87
- 2026-09-10: 87
- 2026-09-09: 87
- 2026-09-08: 86
- 2026-09-07: 86
- 2026-09-06: 85
- 2026-09-05: 85
- 2026-09-04: 84
- 2026-09-03: 84
- 2026-09-02: 72
- 2026-09-01: 72
- 2026-08-31: 83
- 2026-08-30: 82
- 2026-08-29: 82
- 2026-08-28: 81
- 2026-08-27: 66
- 2026-08-26: 54

## Common questions

### What is the uploads.sh MCP server?

uploads.sh is an MCP server listed in the public MCP registry as sh.uploads/mcp. Host files from coding agents; stage on a branch and attach to GitHub PRs. This page covers its npm package (@buildinternet/uploads).

### Is the uploads.sh MCP server safe to use?

uploads.sh scores 92 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 20 September 2026. It declares no install or post-install scripts. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the uploads.sh MCP server expose?

uploads.sh exposes 24 tools: gallery_create, gallery_get, gallery_add, gallery_link, gallery_find_by_reference, and 19 more. Their descriptions and schemas cost roughly 5,092 tokens of context every time the server is loaded.

### Is the uploads.sh MCP server still maintained?

uploads.sh is still listed as active in the MCP registry. We last reached this channel on 20 September 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the uploads.sh MCP server under?

uploads.sh declares the Apache-2.0 licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- npm package: https://www.npmjs.com/package/@buildinternet/uploads
- Socket report: https://socket.dev/npm/package/@buildinternet/uploads
- Repository: https://github.com/buildinternet/uploads
- Website: https://uploads.sh/
- Changelog RSS feed: https://verifymcp.io/servers/sh-uploads-mcp/buildinternet-uploads.xml
- Changelog JSON feed: https://verifymcp.io/servers/sh-uploads-mcp/buildinternet-uploads.json
- HTML version of this page: https://verifymcp.io/servers/sh-uploads-mcp/buildinternet-uploads