@amana/mcp-files

MCP (Model Context Protocol) server for the amana Files service — secure, scalable cloud storage with pre-signed URL upload/download workflows.

Overview

This package exposes the Files API as MCP tools, allowing AI agents to manage file uploads, downloads, and metadata in amana's cloud storage via natural language.

Installation

npm install @amana/mcp-files
# or
npx @amana/mcp-files

Requirements

| Environment Variable | Description | Required | |---|---|---| | AMANA_API_KEY | Your amana platform API key | ✅ | | AMANA_API_BASE_URL | Base URL of the amana gateway | ✅ |

Configuration

Claude Desktop / Cursor

Add to your claude_desktop_config.json or Cursor MCP settings:

{
  "mcpServers": {
    "amana-files": {
      "command": "npx",
      "args": ["@amana/mcp-files"],
      "env": {
        "AMANA_API_KEY": "amana_key_xxxxxxxx",
        "AMANA_API_BASE_URL": "https://api.amana.io"
      }
    }
  }
}

Compy

In Compy's MCP configuration panel, add:

• Command: npx @amana/mcp-files
• Env: Set AMANA_API_KEY and AMANA_API_BASE_URL

Available Tools

| Tool Name | Description | |---|---| | files_upload_file | Get a pre-signed URL to upload a single file (max 5GB) | | files_batch_upload | Get pre-signed URLs for multiple files at once (max 20) | | files_get_download_url | Get a pre-signed URL to download a file | | files_get_file_info | Get metadata about a stored file | | files_delete_file | Delete a file from amana storage |

Upload Workflow

Files are uploaded via pre-signed URLs (S3-compatible). The workflow is:

1. Request upload URL → files_upload_file (returns presigned_url + file_id)
2. Upload directly to S3 → PUT {presigned_url} with file binary
3. Use file_id in downstream services (Shelf, Qosmo, etc.)

Example Usage (Natural Language)

"Get an upload URL for a 50MB MP4 video file named 'commercial.mp4'"

"Get a download link for file ID file_abc123"

"Delete the file with ID file_old456"

"Upload these 5 images in batch: photo1.jpg, photo2.jpg..."

Related Packages

• @amana/mcp-shelf — Register uploaded files as managed digital assets
• @amana/mcp-qosmo — Generate AI music from uploaded videos

License

MIT © amana Inc.