Download attachment
download_attachmentDownload an attachment to a file on the server machine, streaming large files to disk in chunks. Returns file path, size, type, and SHA-256 for verification.
Instructions
Download an attachment's bytes to a file on the machine running this server.
Use it once list_attachments (or get_work_package(include=['attachments'])) has given you an attachment_id. Metadata is read first, then the bytes are streamed to disk in chunks with progress notifications, so a large file neither stalls the call nor buffers in memory.
Returns path, file_name, size_bytes, content_type and the SHA-256 of the bytes (use it to verify or de-duplicate). With return_image=true an image of at most 1 MB comes back as an inline image block as well.
Pitfalls: the file is written on the server's machine, which is the user's machine only in a local (stdio) deployment — tell the user the returned path rather than assuming they can see it. Quarantined attachments fail with attachment_quarantined and are never fetched. An attachment whose virus scan is unfinished answers 401 for everyone except its uploader. Transfers above OPENPROJECT_MCP_MAX_DOWNLOAD_MB (default 100) are refused up front and aborted mid-stream, leaving no partial file. A name collision in the target directory saves as 'name (2).ext' and says so in notes.
Related: list_attachments produces attachment_id; upload_attachment is the reverse direction.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| save_dir | No | Absolute directory to save into; it is created when missing. Defaults to OPENPROJECT_MCP_DOWNLOAD_DIR, and otherwise to an 'openproject-downloads' folder beside the server's working directory. Relative paths are rejected because the server's working directory is not the user's. | |
| return_image | No | Also return the file as an inline image so the model can look at it. Honored only for image/* content of at most 1 MB; otherwise the file is still saved and a note explains why nothing was shown. | |
| attachment_id | Yes | Numeric attachment id from list_attachments or get_work_package(include=['attachments']). Not a work package id. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path of the saved file on the MCP server's machine. | |
| notes | No | Degradation markers: renamed target, image not shown inline, … | |
| sha256 | Yes | SHA-256 of the downloaded bytes, hex encoded. | |
| file_name | Yes | Name the file was saved under; may differ from the attachment's own name when it collided with an existing file. | |
| size_bytes | Yes | Bytes actually written to disk. | |
| content_type | No | MIME type reported by OpenProject. |