catbox-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,213 @@
+# 🐱 Catbox MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [Catbox.moe](https://catbox.moe) — a free file hosting service. Upload files via URL, manage albums, and delete files directly from your MCP client (Claude Desktop, Claude Code, etc.).
+
+[![npm version](https://img.shields.io/npm/v/catbox-mcp-server)](https://www.npmjs.com/package/catbox-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+---
+
+## ⚠️ Important: Anonymous vs Authenticated
+
+Catbox has two user tiers. Understanding this is key:
+
+| Capability | 🕶️ Anonymous | 🔑 With Userhash |
+|-----------|:---:|:---:|
+| **Upload files** | ✅ | ✅ |
+| **Delete files** | ❌ | ✅ |
+| **Create album** | ✅ (but **cannot** edit/delete later) | ✅ (fully manageable) |
+| **Edit album** | ❌ | ✅ |
+| **Add/remove album files** | ❌ | ✅ |
+| **Delete album** | ❌ | ✅ |
+
+You can get a free userhash by uploading any file to [Catbox.moe](https://catbox.moe) — see [Getting Your Userhash](#-getting-your-userhash).
+
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| ☁️ **URL Upload** | Upload files from any publicly accessible URL |
+| 🗑️ **File Management** | Delete files you've uploaded |
+| 🖼️ **Album Management** | Create, edit, add to, remove from, and delete albums |
+
+## 🧰 Tools
+
+| Tool | Description |
+|------|-------------|
+| `url_upload` | Upload a file from a publicly accessible URL |
+| `delete_files` | Delete uploaded files (userhash required) |
+| `create_album` | Create a new album |
+| `edit_album` | Edit album title/description/files (userhash required) |
+| `add_to_album` | Add files to an album (userhash required) |
+| `remove_from_album` | Remove files from an album (userhash required) |
+| `delete_album` | Delete an album (userhash required) |
+
+See the [userhash guide](#-getting-your-userhash) to set up authentication for management tools.
+
+## 📦 Installation
+
+### Via npm (recommended)
+
+```bash
+npm install -g catbox-mcp-server
+```
+
+### Via npx (no install)
+
+```bash
+npx -y catbox-mcp-server
+```
+
+### From source
+
+```bash
+git clone https://github.com/xxy9468615/catbox.git
+cd catbox
+npm install
+node index.js
+```
+
+## 🔧 Configuration
+
+### Claude Desktop / Claude Code
+
+Add to your `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "catbox": {
+      "command": "npx",
+      "args": ["-y", "catbox-mcp-server"],
+      "env": {
+        "CATBOX_USERHASH": "your-catbox-userhash-here"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CATBOX_USERHASH` | ❌ | — | Your Catbox user hash for authentication. Set this to avoid passing it with every call. |
+
+> **💡 Tip:** You can always override the userhash per-tool call by passing it as a parameter — the environment variable is just a convenient default.
+
+### 🔑 Getting Your Userhash
+
+No account registration required — you get a userhash just by using Catbox:
+
+1. Go to [Catbox.moe](https://catbox.moe)
+2. Upload **any file** from your computer (or use this API to upload a URL)
+3. After upload, the page displays your **userhash** — a hex string like `a1b2c3d4e5f6...`
+4. **Save it** and use it with any management tool
+5. You can also get the userhash from the API response when uploading without one
+
+> **💡 Without userhash:** You can upload files and create albums, but:
+> - You **cannot** delete any files
+> - Albums created anonymously are **permanent and unmodifiable** — no edits, no deletions
+> - To manage anything, you need your userhash
+
+## 🚀 Usage Examples
+
+### Upload a file from URL
+
+```json
+{
+  "url": "https://example.com/image.jpg"
+}
+```
+
+Response:
+```
+https://files.catbox.moe/abc123.jpg
+```
+
+### Upload with userhash (to claim ownership)
+
+```json
+{
+  "url": "https://example.com/image.jpg",
+  "userhash": "a1b2c3d4e5f6"
+}
+```
+
+### Create an album
+
+```json
+{
+  "title": "My Vacation Photos",
+  "files": "abc123.jpg def456.png",
+  "desc": "Summer 2026 trip",
+  "userhash": "a1b2c3d4e5f6"
+}
+```
+
+### Add files to an album
+
+```json
+{
+  "short": "album123",
+  "files": "ghi789.jpg jkl012.png",
+  "userhash": "a1b2c3d4e5f6"
+}
+```
+
+### Delete files
+
+```json
+{
+  "files": "abc123.jpg def456.png",
+  "userhash": "a1b2c3d4e5f6"
+}
+```
+
+## 🔗 Links
+
+- **Catbox.moe**: [https://catbox.moe](https://catbox.moe)
+- **Catbox API / Tools**: [https://catbox.moe/tools.php](https://catbox.moe/tools.php)
+- **Catbox FAQ**: [https://catbox.moe/faq.php](https://catbox.moe/faq.php)
+- **GitHub Repo**: [https://github.com/xxy9468615/catbox](https://github.com/xxy9468615/catbox)
+
+## 📄 License
+
+MIT
+
+---
+
+## ⚖️ Disclaimer
+
+This MCP server is an **unofficial community tool** and is **not affiliated with, endorsed by, or sponsored by Catbox LLC**.
+
+### Your Responsibilities
+
+By using this tool, you agree to comply with [Catbox's Terms of Service](https://catbox.moe/legal.php):
+
+- **You own your content** — you must have the right to upload, share, and store any files you upload via this tool
+- **No illegal use** — do not upload copyrighted content without permission, malware, spyware, or any material that violates applicable laws
+- **No commercial use** — Catbox prohibits commercial use of their service without prior written approval from Catbox Executives
+- **No reselling** — you may not resell or supply Catbox services to others
+- **No abuse** — do not spam, harass, or damage Catbox's infrastructure
+
+### No Warranty
+
+This tool is provided **"AS IS"**, without any express or implied warranty. The authors are not responsible for:
+
+- Any content uploaded or shared through this tool
+- Any loss of data, files, or access to Catbox services
+- Any damages arising from the use or inability to use this tool
+- Any violations of Catbox's Terms of Service by end users
+
+**Use at your own risk.** If you have concerns about specific content or usage, contact Catbox at **admin@catbox.moe**.
+
+---
+
+## ☕ Support Catbox
+
+Catbox.moe provides a **free** file hosting service with no accounts required. If you find this service useful, consider supporting them:
+
+- **Ko-fi**: [https://ko-fi.com/catboxmoe](https://ko-fi.com/catboxmoe)
+- **Spread the word** — tell others about Catbox!
+- **Follow their rules** — be a responsible user so the service stays alive for everyone ❤️

package/index.js

@@ -0,0 +1,171 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import FormData from "form-data";
+import axios from "axios";
+
+const CATBOX_API = "https://catbox.moe/user/api.php";
+const DEFAULT_USERHASH = process.env.CATBOX_USERHASH || null;
+
+// ========== 工具定义 ==========
+
+const TOOLS = [
+  {
+    name: "url_upload",
+    description: "通过 URL 上传文件到 Catbox",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "文件的直接链接" },
+        userhash: { type: "string", description: "用户哈希（可选，匿名上传不填）" },
+      },
+      required: ["url"],
+    },
+  },
+  {
+    name: "delete_files",
+    description: "删除已上传的文件",
+    inputSchema: {
+      type: "object",
+      properties: {
+        files: { type: "string", description: "要删除的文件名，空格分隔" },
+        userhash: { type: "string", description: "用户哈希" },
+      },
+      required: ["files", "userhash"],
+    },
+  },
+  {
+    name: "create_album",
+    description: "创建相册",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "相册标题" },
+        files: { type: "string", description: "文件名，空格分隔" },
+        userhash: { type: "string", description: "用户哈希（可选，匿名创建后无法编辑）" },
+        desc: { type: "string", description: "相册描述（可选）" },
+      },
+      required: ["title", "files"],
+    },
+  },
+  {
+    name: "edit_album",
+    description: "编辑相册（必须提供所有参数）",
+    inputSchema: {
+      type: "object",
+      properties: {
+        short: { type: "string", description: "相册短 ID" },
+        title: { type: "string", description: "相册标题" },
+        files: { type: "string", description: "文件名，空格分隔" },
+        userhash: { type: "string", description: "用户哈希" },
+        desc: { type: "string", description: "相册描述" },
+      },
+      required: ["short", "title", "files", "userhash"],
+    },
+  },
+  {
+    name: "add_to_album",
+    description: "向相册添加文件",
+    inputSchema: {
+      type: "object",
+      properties: {
+        short: { type: "string", description: "相册短 ID" },
+        files: { type: "string", description: "文件名，空格分隔" },
+        userhash: { type: "string", description: "用户哈希" },
+      },
+      required: ["short", "files", "userhash"],
+    },
+  },
+  {
+    name: "remove_from_album",
+    description: "从相册移除文件",
+    inputSchema: {
+      type: "object",
+      properties: {
+        short: { type: "string", description: "相册短 ID" },
+        files: { type: "string", description: "文件名，空格分隔" },
+        userhash: { type: "string", description: "用户哈希" },
+      },
+      required: ["short", "files", "userhash"],
+    },
+  },
+  {
+    name: "delete_album",
+    description: "删除相册",
+    inputSchema: {
+      type: "object",
+      properties: {
+        short: { type: "string", description: "相册短 ID" },
+        userhash: { type: "string", description: "用户哈希" },
+      },
+      required: ["short", "userhash"],
+    },
+  },
+];
+
+// ========== 工具处理 ==========
+
+async function handleToolCall(name, args) {
+  // 使用环境变量中的 userhash 作为默认值
+  const userhash = args.userhash || DEFAULT_USERHASH;
+
+  switch (name) {
+    case "url_upload":
+      return await apiCall({ reqtype: "urlupload", userhash, url: args.url });
+    case "delete_files":
+      if (!userhash) throw new Error("需要 userhash 才能删除文件，请在环境变量 CATBOX_USERHASH 中配置或在参数中传入");
+      return await apiCall({ reqtype: "deletefiles", userhash, files: args.files });
+    case "create_album":
+      return await apiCall({ reqtype: "createalbum", userhash, title: args.title, desc: args.desc, files: args.files });
+    case "edit_album":
+      if (!userhash) throw new Error("需要 userhash 才能编辑相册");
+      return await apiCall({ reqtype: "editalbum", userhash, short: args.short, title: args.title, desc: args.desc || "", files: args.files });
+    case "add_to_album":
+      if (!userhash) throw new Error("需要 userhash 才能添加文件到相册");
+      return await apiCall({ reqtype: "addtoalbum", userhash, short: args.short, files: args.files });
+    case "remove_from_album":
+      if (!userhash) throw new Error("需要 userhash 才能从相册移除文件");
+      return await apiCall({ reqtype: "removefromalbum", userhash, short: args.short, files: args.files });
+    case "delete_album":
+      if (!userhash) throw new Error("需要 userhash 才能删除相册");
+      return await apiCall({ reqtype: "deletealbum", userhash, short: args.short });
+    default:
+      throw new Error(`未知工具: ${name}`);
+  }
+}
+
+async function apiCall(params) {
+  const form = new FormData();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== null) form.append(k, v);
+  }
+  const res = await axios.post(CATBOX_API, form, { headers: form.getHeaders() });
+  return { result: res.data.trim() };
+}
+
+// ========== MCP 服务器 ==========
+
+const server = new Server(
+  { name: "catbox-mcp", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    const result = await handleToolCall(name, args);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: `错误: ${e.message}` }], isError: true };
+  }
+});
+
+// ========== 启动 ==========
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "catbox": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "catbox-mcp-server@latest"
+      ],
+      "type": "stdio",
+      "env": {
+        "CATBOX_USERHASH": "你的猫盒哈希值，可在环境变量配置，调用时可覆盖"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "catbox-mcp-server",
+  "version": "1.0.0",
+  "description": "Catbox.moe MCP Server - 文件上传托管服务",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "catbox-mcp-server": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.7.0",
+    "axios": "^1.6.0",
+    "form-data": "^4.0.0"
+  }
+}