内容
# ftp-upload-mcp
[English](./README.md) | [中文](./README.zh-CN.md)
MCP 服务器：通过 FTP 上传本地文件并获取 HTTPS URL。
工具：`upload_file`，`upload_files`。
## 工作流程
```text
本地文件 → FTP（uuid + 原始扩展名）→ MEDIA_PUBLIC_BASE_URL + 路径
```
FTP 目录和 `MEDIA_PUBLIC_BASE_URL` 必须指向相同的文件。
## 使用方法
```bash
npx -y @oyji1992/ftp-upload-mcp@latest
```
### 通用 MCP 配置（Claude Desktop / Cursor / 等）
```json
{
"mcpServers": {
"ftp-upload": {
"command": "npx",
"args": ["-y", "@oyji1992/ftp-upload-mcp@latest"],
"env": {
"MEDIA_FTP_HOST": "<ftp-host>",
"MEDIA_FTP_PORT": "21",
"MEDIA_FTP_USER": "<ftp-user>",
"MEDIA_FTP_PASSWORD": "<ftp-password>",
"MEDIA_PUBLIC_BASE_URL": "https://<cdn-host>/files",
"MEDIA_REMOTE_DIR": "media"
}
}
}
}
```
### Codex (`~/.codex/config.toml`)
```toml
[mcp_servers.ftp-upload]
type = "stdio"
command = "npx"
args = ["-y", "@oyji1992/ftp-upload-mcp@latest"]
startup_timeout_sec = 30
[mcp_servers.ftp-upload.env]
MEDIA_FTP_HOST = "<ftp-host>"
MEDIA_FTP_PORT = "21"
MEDIA_FTP_USER = "<ftp-user>"
MEDIA_FTP_PASSWORD = "<ftp-password>"
MEDIA_PUBLIC_BASE_URL = "https://<cdn-host>/files"
MEDIA_REMOTE_DIR = "media"
```
`@latest` 版本标记是故意的。在此软件包自己的源代码检出中，npm 11 会将根项目误认为是请求的软件包，然后失败，因为软件包没有自链接的二进制文件。解析已发布的版本标记避免了这种歧义。像 `@oyji1992/ftp-upload-mcp@1.0.2` 这样的确切版本也适用于普通的消费者目录。
## 环境变量
所有这些都应在 MCP 配置中设置。有些变量如果省略，则具有默认值。
| 变量名 | 默认值 | 描述 |
| --- | --- | --- |
| `MEDIA_FTP_HOST` | 无 | FTP 主机 |
| `MEDIA_FTP_PORT` | `21` | FTP 端口 |
| `MEDIA_FTP_USER` | 无 | 用户名 |
| `MEDIA_FTP_PASSWORD` | 无 | 密码 |
| `MEDIA_PUBLIC_BASE_URL` | 无 | HTTPS 基本 URL（必须为 `https://`） |
| `MEDIA_REMOTE_DIR` | 空 | FTP 登录主目录下的远程子目录 |
纯 FTP（无 FTPS/SFTP）。请将真实凭证排除在 git 之外。
## 工具
### `upload_file`
```json
{ "file_path": "/absolute/path/to/shot.png" }
```
```json
{
"original_filename": "shot.png",
"stored_filename": "<uuid>.png",
"remote_path": "media/<uuid>.png",
"public_url": "https://<cdn-host>/files/media/<uuid>.png"
}
```
### `upload_files`
```json
{ "file_paths": ["/path/a.png", "/path/b.mp4"] }
```
返回 `{ "uploads": [ ... ] }`。
## 开发
```bash
npm install
npm run build
npm start
```
运行 `npm test` 进行端到端测试。它在 localhost 上启动一个隔离的 FTP 服务器，通过 MCP stdio 调用 `upload_file`，并在磁盘上验证上传的文件。它永远不会使用 MCP 配置文件中的 FTP 凭证。
## 许可证
MIT
