file2url-mcp

突破大模型输入限制的本地文件上传服务 - 纯本地运行，安全无忧。

核心价值

当大模型不支持直接上传图片、文件或突破文本输入限制时，file2url-mcp 提供了一个纯本地上传方案：

• 突破输入限制：让不支持文件上传的大模型通过 URL 读取图片、文档等内容
• 批量内容注入：一次上传多个文件，为大模型提供更丰富的上下文信息
• 纯本地运行：所有文件仅在本地服务器流转，不会上传到任何第三方服务器
• 安全可控：文件存储在本地，30 分钟后自动清理，无数据泄露风险

功能特性

| 功能 | 描述 | 适用场景 | |------|------|---------| | 图片上传 | PNG、JPG、GIF 等常见图片格式 | 视觉分析、图表解读 | | 文件上传 | 任意类型文件（PDF、压缩包等） | 文档分析、资料检索 | | 文本上传 | 将文本保存为自定义格式文件，支持 .txt/.md/.json 等 | 突破 token 限制、批量注入内容 | | 批量操作 | 支持一次上传多个文件/图片 | 为大模型提供完整上下文 |

为什么需要这个工具？

大模型输入限制的痛点

1. 不支持图片上传：部分大模型仅支持文本输入，无法直接分析图片
2. 文件上传受限：某些场景下大模型不支持文件附件
3. 上下文长度有限：长文本内容无法一次性输入
4. 多文件处理困难：无法同时提供多个参考文件

解决方案

本地文件 → file2url-mcp → 本地 URL → 大模型读取

通过将本地文件转换为本地 URL 地址，让任何支持 URL 读取的大模型都能访问您的文件内容。

安全特性

• 纯本地运行：服务器仅在本机 127.0.0.1:3001 监听
• 不上传第三方：文件不离开您的设备，不经过任何云端服务
• 自动清理：30 分钟后文件自动删除，无持久化存储
• 进程隔离：MCP 服务与文件服务分离，互不影响

快速开始

安装依赖

npm install

构建项目

npm run build

MCP 集成

在 Claude Desktop 中使用

在 claude_desktop_config.json 中添加以下配置：

{
  "mcpServers": {
    "file2url-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "file2url-mcp@latest"
        "--port=3001"
      ]
    }
  }
}

注意：首次连接 MCP 时，服务器会自动启动本地上传服务。

服务管理

本章节介绍如何管理图片上传服务的生命周期，包括启动、关闭和重启操作。

服务状态

服务器运行时会占用本地端口 127.0.0.1:3001（或自定义端口），提供以下功能：

• 图片、文件、文本上传
• Web 页面访问（http://127.0.0.1:3001）
• REST API 接口

启动服务

服务会在以下情况自动启动：

情况一：首次安装并注册 MCP

• 在 Claude Desktop 等 MCP 客户端中首次连接 file2url-mcp
• 服务器会自动在后台启动，无需手动操作

情况二：MCP 客户端重启后自动启动

• 当 MCP 客户端重新启动时，如果服务未运行会自动启动

情况三：手动启动（通过 MCP 工具）

// 通过 MCP 工具手动启动服务器
await mcp.callTool("start_image_server");

关闭服务

推荐方式：通过 Web 页面手动关闭

1. 打开浏览器访问 http://127.0.0.1:3001
2. 点击页面上的"关闭服务"按钮
3. 服务会自动优雅关闭，停止监听端口

备选方式：通过 MCP 工具关闭

// 通过 MCP 工具关闭服务器
await mcp.callTool("stop_image_server");

备选方式：手动终止进程

# 查找占用端口的进程
netstat -ano | findstr :3001

# 终止进程（将 PID 替换为实际进程 ID）
taskkill /PID <PID> /F

重启服务

如果需要重启服务（如遇到异常或配置更新），请按以下步骤操作：

1. 关闭服务

   • 通过 Web 页面点击"关闭服务"按钮，或
   • 使用 MCP 工具 stop_image_server

2. 重新启动 MCP 服务器

   • 在 Claude Desktop 等 MCP 客户端的设置中
   • 关闭 file2url-mcp 服务器
   • 重新开启 file2url-mcp 服务器
   • 服务器启动后会自动检测服务状态，未运行则自动启动

服务管理示例

// 检查服务状态
const status = await mcp.callTool("get_server_status");

// 如果服务未运行，启动服务
if (!status.text.includes("正在运行")) {
  await mcp.callTool("start_image_server");
}

// 使用完毕后关闭服务
await mcp.callTool("stop_image_server");

注意事项

• 服务关闭后，上传的文件会被清理，无法通过 URL 访问
• MCP 客户端重启后，如果服务未运行会自动重新启动
• 建议在长时间不需要使用时手动关闭服务，释放系统资源

可用工具

| 工具名称 | 描述 | 参数 | |---------|------|------| | start_image_server | 启动图片上传服务器 | 无 | | get_server_status | 检查服务器运行状态 | 无 | | upload_image | 上传图片文件，获取 URL | imageUrl: 图片绝对路径 | | upload_file | 上传任意文件，获取 URL | fileUrl: 文件绝对路径 | | upload_text | 上传文本内容，保存为自定义格式文件 | content: 文本内容，filename: 可选文件名（支持自定义扩展名如 .txt/.md/.json） |

使用示例

// 一次性上传多张图片，为大模型提供完整视觉上下文
await mcp.callTool("upload_image", { imageUrl: "C:/data/chart1.png" });
await mcp.callTool("upload_image", { imageUrl: "C:/data/chart2.png" });
await mcp.callTool("upload_image", { imageUrl: "C:/data/diagram.png" });

// 上传文档供大模型分析
await mcp.callTool("upload_file", { fileUrl: "C:/docs/report.pdf" });
await mcp.callTool("upload_file", { fileUrl: "C:/docs/spec.pdf" });

// 注入长文本内容（默认保存为 .txt）
await mcp.callTool("upload_text", {
  content: "这是要分析的详细文本内容...",
  filename: "analysis.txt"
});

// 自定义文本格式（如保存为 Markdown）
await mcp.callTool("upload_text", {
  content: "# 标题\n\n这是 Markdown 格式的文本内容...",
  filename: "readme.md"
});

// 保存为 JSON 格式
await mcp.callTool("upload_text", {
  content: '{"key": "value", "data": [1, 2, 3]}',
  filename: "data.json"
});

典型使用场景

场景一：视觉分析

当大模型不支持图片上传时：

// 上传截图
const result = await mcp.callTool("upload_image", {
  imageUrl: "C:/Users/example/screenshot.png"
});
// 返回: { "url": "http://127.0.0.1:3001/uploads/image_123456.png" }
// 大模型通过 URL 读取图片内容进行分析

场景二：批量文件分析

提供多个参考文件：

// 批量上传多个文档
const files = [
  "C:/docs/需求文档.pdf",
  "C:/docs/设计文档.pdf",
  "C:/docs/API文档.pdf"
];

for (const file of files) {
  await mcp.callTool("upload_file", { fileUrl: file });
}

场景三：长文本注入

突破文本输入限制：

// 将长文章分段上传
const longText = "很长的文本内容...";
await mcp.callTool("upload_text", {
  content: longText,
  filename: "context.txt"
});

API 端点

服务器启动后提供以下 REST API 接口：

上传文件

POST /upload
Content-Type: multipart/form-data

参数：

• file: 要上传的文件（二进制数据）
• type: 上传类型，可选值为 image、file、text

响应：

{
  "url": "http://localhost:3001/uploads/image_123456.png",
  "filename": "image_123456.png",
  "originalname": "original.png"
}

健康检查

GET /health

响应：

{
  "status": "ok",
  "port": 3001
}

文件列表

GET /api/files

响应：

{
  "files": [
    {
      "filename": "image_123456.png",
      "url": "http://localhost:3001/uploads/image_123456.png",
      "size": 12345,
      "mtime": 1704067200000
    }
  ]
}

删除文件

DELETE /api/files
Content-Type: application/json

请求体：

{
  "filename": "image_123456.png"
}

响应：

{
  "success": true
}

配置

环境变量

| 变量 | 默认值 | 描述 | |-----|--------|------| | PORT | 3001 | 服务器监听端口 | | HOST | 127.0.0.1 | 服务器绑定地址 |

MCP 端口配置

默认端口为 3001，可通过以下方式自定义端口：

方式一：命令行参数

在 MCP 配置中通过命令行参数指定端口：

{
  "mcpServers": {
    "file2url-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "file2url-mcp@latest"
        "--port=3001"
      ]
    }
  }
}

优先级：命令行参数 > 环境变量 > 默认值

项目结构

file2url-mcp/
├── index.ts              # MCP 服务器入口
├── server.ts             # Express 服务器
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript 配置
├── public/               # 静态文件目录
│   └── index.html        # 上传页面
├── dist/                 # 编译输出
├── uploads/              # 上传文件存储目录
└── README.md             # 文档

技术栈

• TypeScript: 类型安全
• Express.js: Web 服务器框架
• @modelcontextprotocol/sdk: MCP 协议实现
• Multer: 文件上传中间件
• CORS: 跨域资源共享

工作原理

架构设计

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop  │────▶│   MCP Server    │────▶│  Local Server   │
│  (大模型客户端)   │     │  (file2url-mcp) │     │ (127.0.0.1:3001)│
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │   本地文件系统    │
                                               │   (不上传云端)   │
                                               └─────────────────┘

文件上传流程

1. 通过 MCP 工具调用 upload_image、upload_file 或 upload_text
2. 服务器接收本地文件路径或内容
3. 生成唯一文件名（格式：类型_时间戳.扩展名）
4. 保存到本地 uploads 目录
5. 返回本地 URL（http://127.0.0.1:3001/uploads/xxx）
6. 大模型通过 URL 读取文件内容

自动启动机制

1. MCP 客户端连接服务器时触发工具列表请求
2. 服务器检查端口 3001 是否有服务运行
3. 未运行则自动启动后台服务器进程
4. 以 detached 模式运行，不阻塞 MCP 主进程
5. 启动后持续检查服务状态，直到确认可用

扩展能力

网页访问支持

如果大模型不支持直接访问网页 URL，可以配合以下 MCP 服务器实现网页内容获取：

Playwright MCP Server

{
  "mcpServers": {
    "Playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@executeautomation/playwright-mcp-server"
      ],
      "env": {}
    }
  }
}

Puppeteer MCP Server

{
  "mcpServers": {
    "Puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ],
      "env": {}
    }
  }
}

配合使用示例：

1. 使用上传本地图片，获取 URL
2. 使用 Playwright/Puppeteer 访问网页并截图或提取内容
3. 大模型通过 URL 读取本地文件，通过 MCP 工具获取网页信息

常见问题

Q: 文件会上传到云端吗？ A: 不会。所有文件仅在本地服务器和文件系统之间流转，不经过任何第三方服务。

Q: 大模型如何通过 URL 读取文件？ A: 大模型可以配置支持 URL 内容读取功能，直接访问本地 URL 获取文件内容。

Q: 文件会永久保存吗？ A: 不会。文件在 30 分钟后自动删除，确保数据不会长期滞留在本地。

Q: 支持批量上传吗？ A: 支持。可以连续调用多个上传工具，为大模型提供完整的上下文信息。

许可证

MIT License