uploads.sh
NPM · @BUILDINTERNET/UPLOADS · 2 COMPONENTS · SCANNED SEP 20
Host files from coding agents; stage on a branch and attach to GitHub PRs.
Available components
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. How we score → Why this is hard to score →
Supply Chain Security99
- No malware found by supply-chain analysis.Pass
- No known CVEs affecting this package version or its production dependencies.Pass
- No install/post-install scripts declared.Pass
- 5 of 45 dependencies flagged as unhealthy. View diagnostics → Partial
Provenance & Transparency97
- Source repository is publicly reachable at the declared URL. View diagnostics → Pass
- Cryptographically verified build provenance (signed, bound to buildinternet/uploads). View diagnostics → Pass
- Clear OSI-approved license (Apache-2.0).Pass
- Actively maintained (last published 2 days ago).Pass
- Disclosure check failed: no security disclosure policy was found in the source repository. See how to fix → Fail
Schema Quality & AI Usability72
- AI-judged instruction clarity (excellent).Pass
- 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. See how to fix → Fail
- Tools include usage examples.Pass
Stability & Change Management83
- Stability observed for 25 of 30 days with no destabilising changes; credit accrues until the full window elapses.Partial
Tool Coverage100
- 100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
- 100% of tool parameters carry a description.Pass
- Structured output schemas are declared (83% of tools); any adoption earns full credit.Pass
Tool Safety100
- No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.Pass
- All 3 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation.Pass
- An AI judge read all 24 captured unit(s) of tool text and found none that tries to manipulate the model reading it.Pass
Capabilities100
- Implements a current MCP spec version (2026-07-28).Pass
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.
npm · @buildinternet/uploads
claude mcp add sh-uploads-mcp -- npx -y @buildinternet/uploads
{
"mcpServers": {
"sh-uploads-mcp": {
"command": "npx",
"args": [
"-y",
"@buildinternet/uploads"
]
}
}
} {
"servers": {
"sh-uploads-mcp": {
"command": "npx",
"args": [
"-y",
"@buildinternet/uploads"
]
}
}
} codex mcp add sh-uploads-mcp -- npx -y @buildinternet/uploads
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"sh-uploads-mcp": {
"type": "local",
"command": [
"npx",
"-y",
"@buildinternet/uploads"
],
"enabled": true
}
}
} openclaw mcp add sh-uploads-mcp --command npx --arg -y --arg @buildinternet/uploads
mcp_servers:
sh-uploads-mcp:
command: "npx"
args: ["-y", "@buildinternet/uploads"] {
"McpServers": {
"sh-uploads-mcp": {
"Transport": "stdio",
"Command": "npx",
"Arguments": [
"-y",
"@buildinternet/uploads"
]
}
}
} assistant mcp add sh-uploads-mcp -t stdio -c npx -a -y @buildinternet/uploads
{
"mcpServers": {
"sh-uploads-mcp": {
"command": "npx",
"args": [
"-y",
"@buildinternet/uploads"
]
}
}
} Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.
- 20 Sept 26 +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.
- 18 Sept 26 +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.
- 16 Sept 26 +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.
- 15 Sept 26 +15
- Malware scan: unverified → pass ▲ security
- 14 Sept 26 −14
- Malware scan: pass → unverified ▼ security
- Tool safety: pass → unverified ▼ security
- Stability: 0.60 → unverified ▼ security
- Capabilities: pass → unverified ▼ functional
- Tool coverage: 100 → unverified ▼ functional
- First check of Schema quality: unverified functional
- Package version: 0.52.1 → 0.54.0 functional
- 12 Sept 26 +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.
- 9 Sept 26 +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.
- 7 Sept 26 +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.
Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.
Captured 20 Sept 2026 · Analysed npm/@buildinternet/uploads@0.54.0
Provenance Verified
A signed build attestation was found and verified, binding this exact artifact to the source repository it claims to come from.
| Result | Verified |
|---|---|
| Ecosystem | npm |
| Reason | Verified |
| Discovered via | Registry attestation endpoint |
| Source repo | buildinternet/uploads |
| Certificate issuer | https://token.actions.githubusercontent.com |
| Certificate SAN | https://github.com/buildinternet/uploads/.github/workflows/release.yml@refs/heads/main |
| Rekor log index | 2834193479 |
| Predicate type | https://slsa.dev/provenance/v1 |
| Subject digest | sha512:50bd77259b80d65461e6fd03d1f1e8cc296370cd3f381c2ad26732894ca39bef904db3afa747ba3eeb605f4a69083acb69f51224a2981ac8dcadf834e |
Background: How many MCP packages publish verified provenance →
Dependencies 45 packages
| Packages resolved | 45 |
|---|---|
| Stale | 5 |
| Tree resolution | Complete |
Background: SBOMs and build attestations, explained →
The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability. A tool's description is untrusted text the model reads on every call, which is what makes this list a security surface and not just an inventory: how tool poisoning works →
attach Attach to GitHub ~604
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 | yes | 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). |
No output schema declared.
{"files":["./after.png"],"pr":12,"state":"after"}{"files":["./before.png","./after.png"],"pr":12}{"files":["./after.png"],"fromBranch":"old-branch-name","pr":12}changelog Product changelog ~85
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.
| Name | Type | Req | Description |
|---|---|---|---|
| limit | number | – | How many entries to return (default 5, max 50). |
| Name | Type | Req | Description |
|---|---|---|---|
| entries | array | yes | – |
| feed | string | – | – |
| url | string | yes | – |
No examples provided.
comment Sync attachments comment ~138
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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). |
| Name | Type | Req | Description |
|---|---|---|---|
| action | string | – | – |
| commentUrl | string | – | – |
| count | number | – | – |
| fixUrl | string | – | – |
| kind | string | – | – |
| message | string | – | – |
| num | number | – | – |
| posted | boolean | – | – |
| reason | string | – | – |
| repo | string | – | – |
| required | array | – | – |
| via | string | – | – |
{"pr":12}delete Delete file ~69
Delete an uploaded object by key. Set dryRun to preview without deleting.
| Name | Type | Req | Description |
|---|---|---|---|
| dryRun | boolean | – | Report what would be deleted without deleting. |
| key | string | yes | Object key to delete. |
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
| Name | Type | Req | Description |
|---|---|---|---|
| deleted | boolean | – | – |
| dryRun | boolean | – | – |
| key | string | yes | – |
No examples provided.
doctor Diagnose setup ~57
Diagnose the configuration: API health, token auth, and workspace/token alignment. Returns the same report as `uploads doctor --json`, including hints.
| Name | Type | Req | Description |
|---|---|---|---|
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
No output schema declared.
No examples provided.
find_files Find files ~248
Search files by metadata (`filters`) and/or filename substring (`name`). At least one is required. Same as `uploads find`.
| Name | Type | Req | Description |
|---|---|---|---|
| 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). |
| Name | Type | Req | Description |
|---|---|---|---|
| cursor | string|null | – | – |
| items | array | yes | – |
| truncated | boolean | – | – |
{"filters":{"path":"/settings","state":"after"}}{"name":"hero.png"}gallery_add Add gallery item ~114
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.
| Name | Type | Req | Description |
|---|---|---|---|
| altText | string | – | Optional public alt text. |
| caption | string | – | Optional public caption. |
| galleryId | string | yes | Opaque gallery ID. |
| objectKey | string | yes | Existing public object key to add. |
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
| Name | Type | Req | Description |
|---|---|---|---|
| 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 | – | – |
No examples provided.
gallery_create Create gallery ~87
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.
| Name | Type | Req | Description |
|---|---|---|---|
| description | string | – | Optional public gallery description. |
| title | string | yes | Gallery title (1–120 characters). |
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
| Name | Type | Req | Description |
|---|---|---|---|
| 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 | – | – |
No examples provided.
gallery_find_by_reference Find galleries ~106
Find workspace galleries linked to an external reference. Returns gallery summaries and canonical public URLs without contacting the provider.
| Name | Type | Req | Description |
|---|---|---|---|
| coordinate | string | yes | Provider-native external reference coordinate. |
| cursor | string | – | Pagination cursor from a previous response. |
| limit | number | – | Page size (default 50, max 100). |
| provider | string | yes | External provider (currently github). |
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
| Name | Type | Req | Description |
|---|---|---|---|
| galleries | array | – | – |
| nextCursor | string|null | – | – |
No examples provided.
gallery_get Get gallery ~66
Get a workspace-owned gallery, including ordered media and its canonical public URL. Gallery media is public to anyone with the URL.
| Name | Type | Req | Description |
|---|---|---|---|
| galleryId | string | yes | Opaque gallery ID. |
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
| Name | Type | Req | Description |
|---|---|---|---|
| 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 | – | – |
No examples provided.
gallery_link Link gallery ~107
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.
| Name | Type | Req | Description |
|---|---|---|---|
| coordinate | string | yes | Provider-native external reference coordinate. |
| galleryId | string | yes | Opaque gallery ID. |
| provider | string | yes | External provider (currently github). |
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
| Name | Type | Req | Description |
|---|---|---|---|
| canonicalUrl | string|null | – | – |
| coordinate | string | – | – |
| createdAt | string | – | – |
| id | string | – | – |
| kind | string | – | – |
| provider | string | – | – |
| resourceType | string | – | – |
| title | string | – | – |
No examples provided.
get_metadata Get metadata ~66
Read the queryable tags on one file. Returns `{ metadata }` (empty when none). Same as `uploads meta get`.
| Name | Type | Req | Description |
|---|---|---|---|
| key | string | yes | Object key to inspect. |
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
| Name | Type | Req | Description |
|---|---|---|---|
| metadata | object | yes | – |
No examples provided.
list List files ~178
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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). |
| Name | Type | Req | Description |
|---|---|---|---|
| cursor | string|null | – | – |
| items | array | – | – |
| prefixes | array | – | – |
No examples provided.
list_metadata_keys List metadata keys ~91
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`.
| Name | Type | Req | Description |
|---|---|---|---|
| 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). |
| Name | Type | Req | Description |
|---|---|---|---|
| key | string | – | – |
| keys | array | – | – |
| truncated | boolean | – | – |
| values | array | – | – |
No examples provided.
purge_expired Purge expired files ~63
Delete objects older than the workspace retentionDays setting, then reconcile. Skips if retention is unset. Requires files:delete. Same as `uploads purge-expired`.
| Name | Type | Req | Description |
|---|---|---|---|
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
| Name | Type | Req | Description |
|---|---|---|---|
| cutoff | string | – | – |
| deleted | number | – | – |
| freedBytes | number | – | – |
| keys | array | – | – |
| keysTruncated | boolean | – | – |
| reason | string | – | – |
| reconcile | object | – | – |
| retentionDays | number | – | – |
| skipped | boolean | – | – |
| workspace | string | – | – |
No examples provided.
put Upload file ~1,118
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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). |
| Name | Type | Req | Description |
|---|---|---|---|
| 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 | – | – |
{"file":"./after.png","pr":12,"state":"after"}{"branch":"feat/settings","file":"./after.png","state":"after"}{"files":["./before.png","./after.png"],"pr":12}{"contentUrl":"https://cdn.example/settings-after.png","pr":12,"state":"after"}reconcile Reconcile usage ~60
Rebuild usage ledger bytes/objects from storage (source of truth). Preserves the monthly upload counter. Requires files:write. Same as `uploads reconcile`.
| Name | Type | Req | Description |
|---|---|---|---|
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
| Name | Type | Req | Description |
|---|---|---|---|
| bytes | number | – | – |
| changed | boolean | – | – |
| objects | number | – | – |
| previous | object | – | – |
| unprefixedBucket | boolean | – | – |
| usage | object | – | – |
| workspace | string | – | – |
No examples provided.
report Send diagnostic report ~213
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`.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 | yes | Short description of the problem (required, 5–4000 chars). |
| type | string | – | One of: bug, error, idea, other (default: other). |
| Name | Type | Req | Description |
|---|---|---|---|
| hasAttachment | boolean | – | – |
| id | string | – | – |
| ok | boolean | yes | – |
No examples provided.
screenshot Capture screenshot ~1,085
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 | yes | 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). |
No output schema declared.
{"pr":12,"state":"after","target":"http://localhost:4321/settings"}{"fullPage":true,"state":"empty","target":"http://localhost:4321/settings"}search_docs Search uploads.sh docs ~217
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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. |
| Name | Type | Req | Description |
|---|---|---|---|
| query | string | – | – |
| results | array | yes | – |
| total | number | yes | – |
| url | string | yes | – |
No examples provided.
set_metadata Set metadata ~122
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`.
| Name | Type | Req | Description |
|---|---|---|---|
| delete | array | – | Keys to remove. |
| key | string | yes | 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). |
| Name | Type | Req | Description |
|---|---|---|---|
| metadata | object | yes | – |
{"key":"screenshots/settings.png","set":{"path":"/settings","state":"after"}}staged List staged files ~94
List files staged for a git branch and whether they will auto-attach when a PR opens. Returns `{ repo, branch, files, binding }`.
| Name | Type | Req | Description |
|---|---|---|---|
| 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). |
No output schema declared.
No examples provided.
usage Show usage ~50
Workspace storage and monthly upload counters (and remaining headroom when budgets are configured). Same as `uploads usage`.
| Name | Type | Req | Description |
|---|---|---|---|
| workspace | string | – | Override the workspace for this call (like the CLI's --workspace flag). |
| Name | Type | Req | Description |
|---|---|---|---|
| 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 | – | – |
No examples provided.
whoami Who am I ~54
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`.
Input schema present but exposes no named parameters.
| Name | Type | Req | Description |
|---|---|---|---|
| apiUrl | string | – | – |
| ok | boolean | yes | – |
| scopes | array | – | – |
| signedIn | boolean | – | – |
| userId | string|null | – | – |
| workspace | string | yes | – |
No examples provided.
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.