Zipline Mcp

MCP其他

提供方 dorogoy · 包名 zipline-mcp

其他 stdio · 本地进程 会话登录 社区 / 第三方 Claude DesktopClaudeCursorCodex
查看接入方式

Zipline MCP Server An MCP (Model Context Protocol) server that allows you to upload files to a Zipline-compatible host. This server provides tools for uploading files, validating them, and generating upload commands. Features - Upload files to a Zipline instance - Validate files before uploading - Preview upload commands - Get only the download URL after upload - List and search user files st

一句话选型结论

按资料字段整理

Zipline Mcp 属于其他类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类其他 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

其他
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

file upload mcp server

支持客户端

适用场景

file uploadmcp server

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
npx -y zipline-mcp

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Cross-platform,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
接入外部数据

把外部系统的数据接进对话。

自动化重复操作

把固定步骤交给模型跑。

补充工具能力

给模型补上它原本没有的能力。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在其他场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Zipline Mcp当前 未标注 stdio · 本地进程 本地部署 有 未标注
gemini-cli 未标注 stdio · 本地进程 本地部署 有 2026-04-13
ext-apps 未标注 stdio · 本地进程 本地部署 有 2026-04-19
northcinder 未标注 stdio · 本地进程 本地部署 有 2026-08-23
fastctx 未标注 stdio · 本地进程 本地部署 有 2026-08-23
quickstart-resources 未标注 stdio · 本地进程 本地部署 有 2026-04-12

服务器档案

其他
字段来自项目仓库与公开索引,中文说明由本站标注
提供方dorogoy上游标注的维护方 dorogoy
分类其他本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时zipline-mcp · Cross-platform本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

41.1 KB
来自项目仓库与上游目录的原文,未做删改

Zipline MCP Server

An MCP (Model Context Protocol) server designed specifically to interact with Zipline, allowing you to upload files to a Zipline-compatible host. This server provides tools for uploading files, validating them, and generating upload commands.

Features

  • Upload files to a Zipline instance
  • Validate files before uploading
  • Preview upload commands
  • Get only the download URL after upload
  • List and search user files stored on the Zipline server
  • List and manage remote folders on the Zipline server
  • Support for multiple file types, including:
  • Text/code: txt, md, gpx, html, json, xml, csv, js, css, py, sh, yaml, yml
  • Images: png, jpg, jpeg, gif, webp, svg, bmp, tiff, ico, heic, avif

Installation

Global Installation

To install the server globally so you can use it with npx:```bash
npm install -g zipline-mcp


### Local Installation

To install the server as a dependency in your project:```bash
npm install zipline-mcp

Usage

Using with npx

If you installed the server globally, you can run it directly:```bash
npx zipline-mcp


### Adding to MCP Client Configuration

To use this server with an MCP client (like Claude Desktop), you need to add it to your client's configuration file.

### MCP-Zipline Integration Guide

#### Quickstart Configuration

Add this minimal configuration to your MCP client (e.g., Claude Desktop):```yaml
# YAML format
mcpServers:
  zipline:
    command: npx
    args: ['-y', 'zipline-mcp']
    environment:
      ZIPLINE_TOKEN: 'your-api-token-here'
      ZIPLINE_ENDPOINT: 'http://localhost:3000'
``````json
// JSON format
{
  "mcpServers": {
    "zipline": {
      "command": "npx",
      "args": ["-y", "zipline-mcp"],
      "environment": {
        "ZIPLINE_TOKEN": "your-api-token-here",
        "ZIPLINE_ENDPOINT": "http://localhost:3000"
      }
    }
  }
}

Detailed Configuration Options

Required Settings
  • command: The executable to run (typically "npx")
  • args: Array containing ["zipline-mcp"]
  • environment.ZIPLINE_TOKEN: Your Zipline API token
  • environment.ZIPLINE_ENDPOINT: The URL of your Zipline server (default is "http://localhost:3000")
Optional Settings
  • environment.ZIPLINE_FORMAT: File naming format. Supported values: "random", "uuid", "date", "name", "gfycat" (alias for "random-words"), "random-words". Defaults to "random".
  • environment.ZIPLINE_ENDPOINT: Custom Zipline server URL
  • environment.ZIPLINE_DISABLE_SANDBOXING: Disable per-user sandboxing for the tmp_file_manager tool. Set to "true" to disable sandboxing and use the shared ~/.zipline_tmp directory for all users. Defaults to "false" (sandboxing enabled).
  • environment.ALLOWED_EXTENSIONS: Override the list of allowed file extensions for upload and validation. Provide a comma-separated list (e.g., .txt,.md,.pdf,.docx). If set, this will replace the default list of allowed extensions. Useful for restricting or expanding supported file types in your deployment.
  • environment.ZIPLINE_ALLOWED_ROOTS: Directories upload_file_to_zipline and validate_file may read. Comma-separated absolute paths (for example /home/me/uploads,/var/zipline/inbox). Each path is resolved with realpath, and so is the file. A symlink is accepted only when its target stays inside one of these directories. An entry that does not exist is ignored and written to the server log; it does not add any readable path. When unset, the only allowed directory is the home directory of the user running the server.

Security Best Practices

  1. Store API tokens in environment variables, not in config files
  2. Use HTTPS for all connections to Zipline servers
  3. Set ZIPLINE_ALLOWED_ROOTS to the directories the agent is supposed to upload from. The server refuses every other path, including a symlink that points outside those directories.
  4. download_external_url resolves DNS on every request and every redirect. If any address is loopback, private, link-local, or a cloud metadata address, the download is refused. The connection uses the address from that lookup, so a later lookup cannot retarget it.

Troubleshooting Common Issues

Authentication Failures
  • Symptom: "Invalid authorization token" errors
  • Solutions:
  • Verify token validity
  • Check for typos in the ZIPLINE_TOKEN value
  • Ensure token is passed via environment variable

Architecture Overview

The Zipline MCP Server acts as a bridge between MCP clients and Zipline's file hosting service. Here's how the components interact:```mermaid
graph LR
A[MCP Client] --> B[MCP Server]
B --> C[Zipline API]
C --> D[(Zipline Storage)]


### Key Components

1. **MCP Client**: Initiates file upload requests (e.g., Claude Desktop)
2. **MCP Server**:
   - Validates files locally
   - Generates upload commands
   - Handles authentication with Zipline
3. **Zipline API**: Processes upload requests and returns URLs
4. **Zipline Storage**: Persistent file storage system

### Typical Workflow

1. Client sends file path to MCP server
2. Server validates file type and size
3. Server constructs authenticated API request
4. Zipline processes upload and returns URL
5. Server formats response for MCP client

### Format Options

The `format` parameter controls how uploaded files are named on the Zipline server. Here are the supported formats:

#### `random`

Generates a random filename with characters, with length defined by the server configuration. This is the default format.

#### `uuid`

Generates a UUID-based filename (e.g., `550e8400-e29b-41d4-a716-446655440000`).

#### `date`

Uses the current date/time formatted according to the server's default date format. Note that date formatting is handled entirely by the Zipline server.

#### `name`

Uses the original filename without its extension (e.g., `document.txt` becomes `document`).

#### `gfycat`

Alias for `random-words`. Provides human-readable "random words" style filenames.

#### `random-words`

Generates human-readable filenames using random words (e.g., `happy-purple-elephant`).

#### Format Normalization and Validation

- **Case-insensitive**: All format values are case-insensitive (e.g., `UUID`, `uuid`, and `Uuid` are equivalent).
- **Alias handling**: `gfycat` is automatically mapped to `random-words`.
- **Error handling**: Invalid format values will result in an "Invalid format" error.
- **Default behavior**: If the format parameter is omitted, the server uses its configured default format (typically `random`).

#### Examples```bash
# Use UUID format
upload_file_to_zipline(filePath: "document.txt", format: "uuid")

# Use human-readable format (via alias)
upload_file_to_zipline(filePath: "document.txt", format: "gfycat")

# Case-insensitive usage
upload_file_to_zipline(filePath: "document.txt", format: "RANDOM-WORDS")

Enhanced Upload Options

The Zipline MCP Server now supports additional optional headers that provide enhanced control over file uploads. These headers are sent as x-zipline-* headers to the Zipline server.

x-zipline-deletes-at

Controls when the uploaded file should be automatically deleted.

Formats:

  • Relative duration: Strings like "1d" (1 day), "2h" (2 hours), "30m" (30 minutes)
  • Absolute date: ISO-8601 format with "date=" prefix, e.g., "date=2025-12-31T23:59:59Z"

Examples:```javascript
// Delete after 24 hours
uploadFile({
filePath: 'document.txt',
format: 'random',
deletesAt: '1d',
});

// Delete at specific date
uploadFile({
filePath: 'document.txt',
format: 'random',
deletesAt: 'date=2025-12-31T23:59:59Z',
});


**Validation:**

- Relative durations must be positive and use valid units (d, h, m)
- Absolute dates must be in ISO-8601 format and specify a future date
- Invalid formats will be rejected with descriptive error messages

#### `x-zipline-password`

Protects the uploaded file with a password. When this header is provided, users will need to enter the password to access the file.

**Format:**

- Non-empty string value

**Examples:**```javascript
uploadFile({
  filePath: 'secret.txt',
  format: 'random',
  password: 'my-secret-password',
});

Validation:

  • Password must be a non-empty string
  • Whitespace-only passwords are rejected
  • Security: Passwords are never logged or exposed in error messages

x-zipline-max-views

Limits the number of times a file can be viewed before it becomes unavailable. Each successful view decrements the counter.

Format:

  • Non-negative integer (0 or greater)

Examples:```javascript
// Allow 10 views
uploadFile({
filePath: 'document.txt',
format: 'random',
maxViews: 10,
});

// Allow single view (disposable link)
uploadFile({
filePath: 'document.txt',
format: 'random',
maxViews: 1,
});


**Validation:**

- Must be an integer ≥ 0
- Negative numbers and non-integer values are rejected
- When counter reaches 0, file becomes eligible for removal

#### `x-zipline-folder`

Specifies the ID of the folder where the upload should be placed. The folder must exist on the Zipline server.

**Format:**

- Alphanumeric string (letters and numbers only)

**Examples:**```javascript
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  folder: 'myfolder123',
});

Validation:

  • Must be a non-empty alphanumeric string
  • Special characters and whitespace are rejected
  • If the specified folder doesn't exist, the upload will fail

Combining Multiple Headers

You can combine multiple headers for enhanced control:javascript uploadFile({ filePath: 'document.txt', format: 'random', deletesAt: '7d', // Delete after 7 days password: 'secret123', // Password protect maxViews: 5, // Allow 5 views folder: 'shared', // Place in "shared" folder });

Error Handling

All headers are validated locally before the upload request is sent to the server. If any header is invalid:

  • The upload is aborted immediately
  • A descriptive error message is returned
  • No HTTP request is made to the Zipline server
  • The error message explains exactly what needs to be fixed

Backward Compatibility

All enhanced headers are optional. Existing code that doesn't use these headers will continue to work exactly as before. The new functionality only activates when you explicitly provide these parameters.

Available Tools

This server provides the following tools:

upload_file_to_zipline

Uploads a file to the Zipline server and returns a detailed success message.

  • filePath: Path to the file to upload. The path must resolve inside ZIPLINE_ALLOWED_ROOTS (the home directory when that variable is unset). The server reads the real path after resolving symlinks. Supported extensions: txt, md, gpx, html, json, xml, csv, js, css, py, sh, yaml, yml, png, jpg, jpeg, gif, webp, svg, bmp, tiff, ico, heic, avif. Binary types are accepted only when the file contents identify that type. Legacy Word, Excel, and PowerPoint files are accepted when the bytes are a Compound File Binary container. AVI is accepted when the bytes are an AVI container (video/vnd.avi). Matroska is accepted when the bytes are Matroska (video/matroska), and WebM when they are WebM. If a Matroska or WebM file starts with an EBML header but the document type is past the first 4100 bytes, the server keeps reading that file until the type is identified. The extension alone is not enough. Text types are accepted only when the bytes contain no NUL. A NUL byte does not skip the secret scan.
  • originalName: (optional) Original filename to preserve during download. This parameter is sent as the x-zipline-original-name header to the Zipline server. The original filename will be used when downloading the file, not when storing it. Must be a non-empty string without path separators.

Example Prompts for Users:

  • "Upload the file '/path/to/document.pdf' to Zipline"
  • "Upload my file at '/home/user/images/photo.jpg' and preserve the original name"
  • "I want to upload '/path/to/data.csv' with the original name 'sales-data.csv'"
  • "Upload file '/path/to/script.py' to Zipline"
  • "Can you upload '/path/to/report.docx' for me?"

validate_file

Checks if a file exists and is suitable for upload.

  • filePath: Path to the file to validate. The same ZIPLINE_ALLOWED_ROOTS rule as upload applies: the real path, after symlinks, must stay inside an allowed directory. Supported extensions: txt, md, gpx, html, json, xml, csv, js, css, py, sh, yaml, yml, png, jpg, jpeg, gif, webp, svg, bmp, tiff, ico, heic, avif. The same content rules as upload apply, including the Compound File, AVI, Matroska, and WebM cases. Unidentified non-text content is rejected rather than trusted because the extension matches.

Example Prompts for Users:

  • "Check if '/path/to/document.pdf' is valid for upload"
  • "Validate the file at '/home/user/images/photo.jpg'"
  • "Is '/path/to/data.csv' suitable for uploading to Zipline?"
  • "Can you validate '/path/to/script.py' for me?"
  • "Check if '/path/to/report.docx' can be uploaded"

list_user_files

Lists and searches files that you have previously uploaded to the Zipline server. Use this tool to find file IDs that can then be used with get_user_file, update_user_file, and delete_user_file tools. You can also obtain file IDs by using get_user_file if you already know the file name.

  • page: (optional) Page number for pagination (default: 1)
  • perPage: (optional) Number of items per page (default: 20)
  • searchField: (optional) Field to search in (e.g., "name", "originalName", "type")
  • searchQuery: (optional) Search query string
  • filter: (optional) Filter by file type or other criteria
  • sort: (optional) Sort field (e.g., "createdAt", "size", "name")
  • order: (optional) Sort order ("asc" or "desc", default: "desc")

Example Prompts for Users:

  • "List all my files on Zipline"
  • "Show me the first page of my uploaded files"
  • "Search for files with 'document' in the name"
  • "Find all PDF files that I've uploaded"
  • "List my files sorted by creation date, newest first"
  • "Show me 10 files per page, page 2"
  • "Search for files with 'report' in the original name"
  • "List my files sorted by size, largest first"
  • "Find all image files I've uploaded"

tmp_file_manager

Minimal, sandboxed file management with per-user isolation. Each user gets their own sandbox directory based on their ZIPLINE_TOKEN. Only bare filenames are allowed (no subdirectories or path traversal). All operations are strictly limited to the user's sandbox.

  • command: One of:
  • LIST — List all files in the user's sandbox
  • CREATE — Create or overwrite a file (optionally provide content)
  • OPEN or READ — Read file content (max 1MB)
  • PATH — Get the absolute path of a file in the sandbox
  • DELETE — Delete a file from the sandbox
  • content: (optional) String content for CREATE

Examples:

  • LIST
  • CREATE notes.txt (with or without content)
  • OPEN notes.txt
  • READ notes.txt
  • PATH notes.txt
  • DELETE notes.txt

Example Prompts for Users:

  • "List all files in my sandbox"
  • "Create a file named 'notes.txt' with content 'Meeting notes from today'"
  • "Read the content of 'config.json'"
  • "Get the absolute path of 'data.csv'"
  • "Delete the file 'temp.txt'"
  • "Show me all files in my temporary directory"
  • "Create a new file called 'draft.md' with some content"
  • "Open and read the 'settings.json' file"
  • "What's the full path to 'output.txt'?"
  • "Remove 'old_file.txt' from my sandbox"

Sandboxing Configuration:

  • Per-user sandboxing is enabled by default
  • To disable sandboxing and use the shared ~/.zipline_tmp directory for all users, set ZIPLINE_DISABLE_SANDBOXING=true in your environment
  • When sandboxing is disabled, session locking and TTL cleanup are also disabled

Per-User Sandboxing (when enabled):

  • Each user gets a unique sandbox directory at ~/.zipline_tmp/users/{hash} where hash is a SHA-256 hash of the user's ZIPLINE_TOKEN
  • Sandboxes are automatically created with 0700 permissions for security
  • All file operations are isolated within the user's sandbox
  • Sandboxes older than 24 hours are automatically cleaned up

Session Locking (when sandboxing is enabled):

  • Each user's sandbox is locked during operations to prevent concurrent access
  • Locks automatically expire after 30 minutes
  • The system prevents race conditions when multiple clients access the same sandbox

Safety:

  • Only bare filenames allowed (no /, \, .., or absolute paths)
  • Any attempt to access outside the user's sandbox is refused with an explicit error
  • Files larger than 1MB cannot be read
  • Subdirectories are not supported
  • Each user's sandbox is isolated from others (when sandboxing is enabled)

download_external_url

A new tool has been added: download_external_url. It lets the MCP server (and therefore models) download an external HTTP(S) URL into the caller's sandbox and returns the absolute filesystem path to the saved file.

  • Tool name: download_external_url
  • Purpose: Download an external HTTP(S) resource into the per-user sandbox and return the absolute path where the file was stored.
  • Input schema:
  • url (string) — required — HTTP or HTTPS URL to download
  • timeoutMs (number) — optional — request timeout in milliseconds (default: 30000)
  • maxFileSizeBytes (number) — optional — maximum allowed file size in bytes (default: 100 _ 1024 _ 1024 = 100 MB)
  • Behavior:
  • Validates the provided URL and only allows http: and https: schemes.
  • Uses an AbortController to enforce the configured timeout.
  • Checks the Content-Length header when present and rejects downloads that declare a size larger than the configured maximum.
  • Downloads into the user's sandbox directory (same sandbox used by the tmp_file_manager tool) and returns the absolute path, e.g. /home/user/.zipline_tmp/users//file.ext.
  • If the remote resource does not provide a filename, a safe deterministic name is used.
  • Partial files are cleaned up on failure to avoid leaving incomplete artifacts in the sandbox.
  • Structured logs are emitted via the existing sandbox logging facility for observability.

Usage example (MCP tool call)

  • Example input:
    {
    "url": "https://example.com/files/document.pdf",
    "timeoutMs": 30000,
    "maxFileSizeBytes": 104857600
    }
  • Example successful response content:
    "✅ DOWNLOAD COMPLETE\n\nLocal path: /home/user/.zipline_tmp/users/abc123/document.pdf"

Security & safety considerations

  • Only http and https are accepted. Other schemes (ftp, file, etc.) are rejected.
  • Before each connection, including after a redirect, the server resolves the hostname and refuses the download if any address is loopback, private, link-local, or a cloud metadata address (for example 127.0.0.1, 10.0.0.0/8, 169.254.169.254).
  • The socket connects to the address returned by that lookup. The original hostname is sent as the Host header and as the TLS server name. A DNS change after the check cannot move the connection.
  • Default file size limit: 100 MB. You can override via maxFileSizeBytes but be cautious.
  • The downloader follows redirects but enforces the maximum redirect behavior in code (to avoid redirect loops). Each redirect is resolved and checked again.
  • When the remote server returns an error status, only the first 1 MiB of the response body is kept. A successful download still uses maxFileSizeBytes (default 100 MB).
  • All downloads are saved inside the per-user sandbox; filenames are validated and sanitized using the same rules as tmp_file_manager (no path separators, no dot segments, no absolute paths).
  • The server logs download activity with sanitized paths (user portion masked) for observability; secrets (such as tokens) are never logged.
  • If you require domain allow-listing to restrict where the server can download from, consider adding a hostname whitelist at the MCP server configuration level before enabling this tool for production usage.

Example Prompts for Users:

  • "Download the PDF from 'https://example.com/document.pdf' to my sandbox"
  • "Download 'https://example.com/data.csv' with a timeout of 60 seconds"
  • "Download the image from 'https://example.com/image.jpg' with a max file size of 50MB"
  • "Download the file from 'https://example.com/report.pdf' and save it to my sandbox"
  • "Can you download 'https://example.com/config.json' for me?"
  • "Download 'https://example.com/archive.zip' with a custom timeout of 45 seconds"
  • "I need to download 'https://example.com/data.json' with a max size of 10MB"

list_user_files

A new tool has been added: list_user_files. It allows you to list and search files that you have previously uploaded to the Zipline server.

  • Tool name: list_user_files
  • Purpose: List and search user files stored on the Zipline server with support for pagination, filtering, sorting, and searching.
  • Input schema:
  • page (number) — optional — Page number for pagination (default: 1)
  • perPage (number) — optional — Number of items per page (default: 20)
  • searchField (string) — optional — Field to search in (e.g., "name", "originalName", "type")
  • searchQuery (string) — optional — Search query string
  • filter (string) — optional — Filter by file type or other criteria
  • sort (string) — optional — Sort field (e.g., "createdAt", "size", "name")
  • order (string) — optional — Sort order ("asc" or "desc", default: "desc")
  • Behavior:
  • Fetches files from the Zipline API with the specified parameters
  • Supports pagination to handle large numbers of files
  • Allows searching within specific fields using searchField and searchQuery
  • Supports filtering and sorting of results
  • Returns a structured response with file information and pagination metadata

Usage example (MCP tool call)

  • Example input:json { "page": 1, "perPage": 10, "searchField": "name", "searchQuery": "document", "sort": "createdAt", "order": "desc" }
  • Example successful response content:```
    📁 USER FILES (Page 1 of 3)
  1. ⭐ document.pdf
    🆔 ID: file123
    📅 Created: 1/15/2025
    📊 Size: 1.2 MB
    🏷️ Type: application/pdf
    👁️ Views: 5
    🔗 URL: https://zipline.example.com/u/file123

  2. image.png
    🆔 ID: img456
    📅 Created: 1/14/2025
    📊 Size: 2.1 MB
    🏷️ Type: image/png
    👁️ Views: 12
    🔗 URL: https://zipline.example.com/u/img456

  3. data.csv
    🆔 ID: csv789
    📅 Created: 1/13/2025
    📊 Size: 500.0 KB
    🏷️ Type: text/csv
    👁️ Views: 3
    🔗 URL: https://zipline.example.com/u/csv789

Total files: 25 | Showing: 3
```

Note: The URLs in the response are normalized to ensure proper formatting regardless of the ZIPLINE_ENDPOINT configuration. The normalization handles trailing slashes and ensures consistent URL construction.

File Model

The tool returns files with the following structure:

  • id: Unique identifier for the file (used for operations like get_user_file, update_user_file, and delete_user_file)
  • name: The filename as stored on the server
  • originalName: The original filename when uploaded
  • size: File size in bytes
  • type: MIME type of the file
  • url: Direct URL to access the file
  • createdAt: When the file was uploaded (ISO 8601 format)
  • expiresAt: When the file will expire (if applicable)
  • maxViews: Maximum view limit (if applicable)
  • views: Current view count

Search and Filter Options

The tool provides powerful search and filtering capabilities:

  • Search: Use searchField and searchQuery to search within specific fields
  • Supported search fields: "name", "originalName", "type"
  • Search is case-insensitive and supports partial matches
  • Filter: Use the filter parameter to filter by file type or other criteria
  • Sort: Use sort and order to sort results by any field
  • Supported sort fields: "createdAt", "size", "name", "views"
  • Order can be "asc" (ascending) or "desc" (descending)

Notes for integrators

  • This tool is exported by the MCP server and can be invoked programmatically by MCP clients or models.
  • The implementation lives in src/userFiles.ts and the MCP registration is in src/index.ts.
  • Tests were added under src/userFiles.test.ts to exercise pagination, searching, filtering, sorting, and error handling.

get_user_file

Information about the tool: get_user_file. It allows you to retrieve detailed information about a specific file stored on the Zipline server. Use list_user_files or the file name to find the file ID you need for this tool.

  • Tool name: get_user_file
  • Purpose: Get detailed information about a specific file stored on the Zipline server
  • Input schema:
  • id (string) — required — File ID to retrieve information for. Obtain this from the list_user_files tool.
  • Behavior:
  • Fetches file information from the Zipline API using the file ID
  • Returns comprehensive file metadata including size, type, views, favorites status, and more
  • Handles URL encoding of special characters in file IDs

Usage example (MCP tool call)

  • Example input:json { "id": "file123" }
  • Example successful response content:```
    📁 FILE INFORMATION

📁 document.pdf
🆔 ID: file123
📅 Created: 1/15/2025
📊 Size: 1.2 MB
🏷️ Type: application/pdf
👁️ Views: 5
🔗 URL: http://localhost:3000/u/file123

📄 Original Name: my-document.pdf
🏷️ Tags: tag1, tag2
📁 Folder ID: folder123
```

Note: The URL in the response is normalized to ensure proper formatting regardless of the ZIPLINE_ENDPOINT configuration. The normalization handles trailing slashes and ensures consistent URL construction.

Example Prompts for Users:

  • "Get detailed information about the file with ID 'abc123'"
  • "Show me the details for file 'document.pdf'"
  • "I need to see the metadata for file 'xyz789'"
  • "What are the properties of the file named 'my-image.jpg'?"
  • "Get information about the file with ID 'file123'"

update_user_file

Information about the tool: update_user_file. It allows you to update properties of a specific file stored on the Zipline server. Use list_user_files or the file name to find the file ID you need for this tool.

  • Tool name: update_user_file
  • Purpose: Update properties of a specific file stored on the Zipline server
  • Input schema:
  • id (string) — required — File ID to update. Obtain this from the list_user_files tool.
  • favorite (boolean) — optional — Set/unset as favorite
  • maxViews (number) — optional — Maximum allowed views (>= 0)
  • password (string | null) — optional — Set password (string), remove password (null)
  • originalName (string) — optional — Set or update the original filename
  • type (string) — optional — Set or update the file MIME type
  • tags (string[]) — optional — Array of tag IDs to set for this file
  • name (string) — optional — Rename the file
  • Behavior:
  • Updates file properties using PATCH request to the Zipline API
  • Only updates fields that are explicitly provided (undefined fields are ignored)
  • Supports setting or removing passwords by passing string or null
  • Returns the updated file information

Usage example (MCP tool call)

  • Example input:json { "id": "file123", "favorite": true, "maxViews": 10, "password": "secret123" }
  • Example successful response content:```
    ✅ FILE UPDATED SUCCESSFULLY!

⭐🔒 document.pdf
🆔 ID: file123
📅 Created: 1/15/2025
📊 Size: 1.2 MB
🏷️ Type: application/pdf
👁️ Views: 5/10

📄 Original Name: my-document.pdf
🏷️ Tags: tag1, tag2
📁 Folder ID: folder123
```

Note: The response does not include the URL field. To get the updated file information with the URL, use the get_user_file tool.

Example Prompts for Users:

  • "Set file 'abc123' as a favorite"
  • "Update file 'document.pdf' to have a maximum of 10 views"
  • "Add password protection to file 'xyz789' with password 'secret123'"
  • "Remove the password from file 'file123'"
  • "Change the original name of file 'abc123' to 'my-updated-document.pdf'"
  • "Rename file 'xyz789' to 'new-name.pdf'"
  • "Set the MIME type of file 'file123' to 'application/pdf'"
  • "Add tags ['tag1', 'tag2'] to file 'abc123'"
  • "Update file 'xyz789' to be a favorite with maxViews of 5 and password 'secure'"

delete_user_file

A new tool has been added: delete_user_file. It allows you to delete a specific file stored on the Zipline server. Use list_user_files or the file name to find the file ID you need for this tool.

  • Tool name: delete_user_file
  • Purpose: Delete a specific file stored on the Zipline server
  • Input schema:
  • id (string) — required — File ID to delete. Obtain this from the list_user_files tool.
  • Behavior:
  • Deletes the file using DELETE request to the Zipline API
  • Returns the file information that was deleted (for confirmation)
  • Handles URL encoding of special characters in file IDs

Usage example (MCP tool call)

  • Example input:json { "id": "uniqueid123" }
  • Example successful response content:```
    ✅ FILE DELETED SUCCESSFULLY!

⭐🔒 document.pdf
🆔 ID: uniqueid123
📅 Created: 1/15/2025
📊 Size: 1.2 MB
🏷️ Type: application/pdf
👁️ Views: 5/10

📄 Original Name: my-document.pdf
🏷️ Tags: tag1, tag2
📁 Folder ID: folder123
```

Note: The response does not include the URL field since the file has been deleted.

Example Prompts for Users:

  • "Delete file with ID 'abc123'"
  • "Remove file 'document.pdf' from the server"
  • "Delete the file named 'my-image.jpg'"
  • "Permanently delete file 'xyz789'"
  • "I want to delete the file with ID 'file123'"

remote_folder_manager

A new tool has been added: remote_folder_manager. It allows you to list and manage remote folders on the Zipline server.

  • Tool name: remote_folder_manager

…(正文过长,页面只展示前面部分,完整内容见仓库)

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Zipline Mcp 怎么安装?

在客户端按下面的安装命令接入:npx -y zipline-mcp。对应的包名是 zipline-mcp。装完在客户端配置里引用同一个包或端点。

Zipline Mcp 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Zipline Mcp 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Zipline Mcp 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

Zipline Mcp 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、Codex、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Zipline Mcp 能提供哪些能力?

资料显示能力标签包括 file upload、mcp server。具体工具清单以官方文档为准。

Zipline Mcp 需要什么运行环境?

运行时为 Cross-platform;属于本地进程,需要在本机装好运行环境。

Zipline Mcp 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。