Curl MCP Server

Curl MCP Server

一个 Model Context Protocol（MCP）服务，通过终端 Shell 集成提供安全的 curl 命令执行能力。

功能

• GET 请求：使用自定义标头执行 HTTP GET 请求
• POST 请求：发送可配置内容类型的 POST 数据
• 自定义命令：在安全限制下执行自定义 curl 命令
• 文件下载：下载文件并获取元数据
• 安全性：内置防护机制，防止危险操作
• 超时：可配置请求超时时间（最长 30 秒）
• 输出限制：防止输出内容过大

安装

# Clone or create the project directory
mkdir curl-mcp-server
cd curl-mcp-server

# Install dependencies
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node tsx

# Create src directory and add the TypeScript code
mkdir src
# Place the server code in src/index.ts

# Build the project
npm run build

先决条件

• Node.js 18+
• PATH 中提供 curl 命令
• TypeScript 编译器

可用工具

1. curl_get

执行 HTTP GET 请求。

参数：

• url（必需）：要请求的 URL
• headers（可选）：以 "Key: Value" 格式表示的标头数组
• timeout（可选）：超时时间，单位为秒（默认值：10，最长：30）
• follow_redirects（可选）：是否跟随 HTTP 重定向（默认值：true）

示例：

{
  "url": "https://api.github.com/user",
  "headers": ["Authorization: token YOUR_TOKEN"],
  "timeout": 15
}

2. curl_post

执行 HTTP POST 请求。

参数：

• url（必需）：要请求的 URL
• data（必需）：要发送的 POST 数据
• content_type（可选）：Content-Type 标头（默认值："application/json"）
• headers（可选）：附加标头数组
• timeout（可选）：超时时间，单位为秒（默认值：10，最长：30）

示例：

{
  "url": "https://api.example.com/data",
  "data": "{\"key\": \"value\"}",
  "content_type": "application/json",
  "headers": ["Authorization: Bearer TOKEN"]
}

3. curl_custom

完全自定义执行 curl 命令。

参数：

• args（必需）：curl 参数数组（不包含 'curl' 命令）
• timeout（可选）：超时时间，单位为秒（默认值：10，最长：30）

示例：

{
  "args": ["-X", "PUT", "-H", "Content-Type: application/json", "-d", "{\"status\": \"updated\"}", "https://api.example.com/resource/123"],
  "timeout": 20
}

4. curl_download

下载文件并获取元数据。

参数：

• url（必需）：要从中下载文件的 URL
• output_file（可选）：输出文件路径
• timeout（可选）：超时时间，单位为秒（默认值：30，最长：30）

示例：

{
  "url": "https://example.com/file.pdf",
  "output_file": "/tmp/downloaded_file.pdf"
}

安全功能

• URL 验证：仅允许 HTTP 和 HTTPS URL
• 参数过滤：屏蔽危险的 curl 标志
• 输出限制：最大输出大小为 1MB，以防止内存问题
• 超时：所有请求均可配置超时时间
• 安全默认值：为所有参数设置合理的默认值

屏蔽的操作

出于安全考虑，以下 curl 操作受到限制：

• 文件上传（--upload-file、--form）
• 加载配置文件（--config）
• 不受限制的文件输出（通过特定工具进行控制）
• 二进制数据上传
• 生成跟踪文件

使用示例

基本 GET 请求

# Through MCP client
{
  "tool": "curl_get",
  "arguments": {
    "url": "https://httpbin.org/get"
  }
}

使用 JSON 数据进行 POST 请求

{
  "tool": "curl_post",
  "arguments": {
    "url": "https://httpbin.org/post",
    "data": "{\"message\": \"hello world\"}",
    "content_type": "application/json"
  }
}

自定义标头

{
  "tool": "curl_get",
  "arguments": {
    "url": "https://api.github.com/user",
    "headers": [
      "Authorization: token ghp_xxxxxxxxxxxx",
      "User-Agent: MyApp/1.0"
    ]
  }
}

运行服务

# Development mode
npm run dev

# Production mode
npm run build
npm start

与 Claude Desktop 集成

添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "curl": {
      "command": "node",
      "args": ["/path/to/curl-mcp-server/build/index.js"]
    }
  }
}

错误处理

该服务会针对以下情况提供详细的错误消息：

• URL 无效
• 超时错误
• curl 执行失败
• 超出输出大小限制
• 违反安全限制

限制

• 请求超时时间最长为 30 秒
• 最大输出大小为 1MB
• 仅支持 HTTP/HTTPS 协议
• 出于安全考虑，屏蔽某些 curl 标志

贡献

欢迎提交问题和改进请求。请务必彻底测试所有更改，尤其是与安全相关的修改。

许可证

MIT 许可证——详情请参阅 LICENSE 文件。