AI导哈

HTTP客户端工具

curl-mcp是一个开源的HTTP/cURL工具，专为模型上下文协议（MCP）设计，提供结构化HTTP客户端功能，适用于AI助手和MCP兼容的开发工具。

  • by calibress
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 calibress/curl-mcp

使用说明

卷曲mcp

curl-mcp 是一个开源的HTTP/cURL工具 模型上下文协议（MCP）.

它提供了一个单一的工具：

curl_request –为AI助手和MCP感知开发工具设计的结构化HTTP客户端。

此服务器用于 任何兼容MCP的客户端例如：

  • ChatGPT桌面
  • Roo代码
  • 光标
  • 克莱恩
  • Continue.dev
  • 定制MCP代理

这里没有包含特定于客户端的配置示例——每个MCP客户端都提供了自己的添加本地MCP服务器的方法。
你只要跑 curl-mcp，然后在您的客户端中注册。

✨ 特性

  • 🔌 MCP传输
    Stdio用于本地开发，基于Express的HTTP服务器用于托管客户端。

  • 🧰 完全HTTP支持
    支持 GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

  • 🧱 结构化响应
    状态、标题、内容类型、时间、大小、正文（文本/漂亮的JSON/base64）、建议。

  • 🍪 会话和重定向控制
    每个主机的内存cookie jar(persist_session), follow_redirects 切换， clear_session 帮手。

  • 🕒 超时和网络处理
    中止控制器，键入错误：超时、DNS、连接、SSL、通用网络。

  • 🧪 集成测试友好
    自我描述JSON场景 docs/integration-tests.json.

🚀 快速开始

  • 来自源（本地克隆）：

    npm install
npm run dev:stdio   # stdio transport
npm run dev:http    # HTTP transport (default: http://localhost:3000/mcp)

  • 从CLI（已安装）：

    brew install calibress/mcp/curl-mcp    # or: npm install -g @calibress/curl-mcp
curl-mcp             # stdio
curl-mcp --http      # HTTP (set PORT or MCP_PORT to change 3000)

然后将MCP客户端指向您使用的命令（请参阅下面的配置）。

📦 安装（来源）

npm install
npm run build

▶️ 运行MCP服务器

你可以跑 curl-mcp 直接从此源代码仓库，或通过您的 PATH.

来自源（本地克隆）

从你当地的根 curl-mcp 克隆：

npm run dev:stdio

这将启动 curl-mcp stdio上的MCP服务器。
配置您的MCP客户端以在repo目录中运行相同的命令。
有些客户端允许您显式设置工作目录；如果你通过了考试，其他人的表现会更好 --prefix 指向你的克隆体。
例如，a mcpServers JSON块可能看起来像：

{
  "mcpServers": {
    "curl-mcp": {
      "command": "npm",
      "args": [
        "--prefix",
        "/PATH/TO/YOUR/curl-mcp",
        "run",
        "dev:stdio"
      ]
    }
  }
}

确保该命令的工作目录是本地的根目录 curl-mcp 克隆。

来自CLI(curl-mcp 在PATH上）

如果 curl-mcp 在你的 PATH （例如通过Homebrew或npm），将MCP客户端直接指向它，而无需使用 npm run:

{
  "mcpServers": {
    "curl-mcp": {
      "command": "curl-mcp",
      "args": []
    }
  }
}

重要提示：
MCP客户端都有自己添加本地MCP服务器和选择工作目录的方法。
使用上述示例作为指导，但请参阅客户的文档以了解确切的配置格式。

HTTP传输（Express）

启动HTTP服务器：

# from source
npm run dev:http
# or from the installed CLI
curl-mcp --http

端口和硬化（可选）：

  • 端口：默认为3000；用以下方式覆盖 PORT 或 MCP_PORT （例如。， PORT=3400 npm run dev:http).
  • MCP客户端配置应与服务器端口匹配，例如。 "url": "http://localhost:3400/mcp".
  • 如果端口正在使用中，请选择另一个空闲端口并将其反映在URL中（一些客户端允许您单独设置主机/端口；否则将端口包含在URL中）。
  • Auth/allowlist（默认：关闭）。通过env变量选择加入：
    • MCP_REQUIRE_KEY=true 和 MCP_API_KEYS=key1,key2 （检查 Authorization: Bearer <key> 或 X-API-Key)
    • MCP_ALLOWED_HOSTS=host:port,otherhost:port （主机标头检查）
    • MCP_ALLOWED_ORIGINS=https://yourapp.com （来源检查+CORS分配列表） 如果未设置，服务器将保持打开状态，供本地/dev使用。

将MCP客户端指向HTTP端点（默认 http://localhost:3000/mcp):

{
  "mcpServers": {
    "curl-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

🔍 烟雾测试（HTTP）

  1. 启动HTTP服务器： npm run dev:http （或 curl-mcp --http).
  2. 运行冒烟脚本： npm run smoke:http （套 MCP_URL 覆盖端点）。
  3. 您应该看到一行摘要，其中包含返回的状态/时间。

🛠 工具： curl_request

输入（模式概述）

{
  "url": "string",
"method": "GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS",
"headers": { "Header-Name": "value" },
"body": "string or null",
"timeout_seconds": 1,
"response_type": "text | json | binary (optional; default text)",
"persist_session": "boolean (optional; per-host cookie jar for chained calls)",
"follow_redirects": "boolean (optional; default true; set false to capture redirect + cookies)",
"clear_session": "boolean (optional; clear stored cookies for this host before the request)"
}

输出（模式概述）

{
  "ok": true,
  "code": 200,
  "status": "OK",
  "message": "Request completed successfully.",
  "timing_ms": 123,
  "size_bytes": 4096,
  "request": { ... },
  "response": {
    "status_code": 200,
    "status_text": "OK",
    "headers": { ... },
    "content_type": "<content-type header, if present>",
    "body": "<raw text body>",
    "body_base64": "<base64 when response_type=binary>",
    "cookies": ["set-cookie if present"]
  },
  "advice": [],
  "error_type": "timeout | dns_error | connect_error | ssl_error | network_error (when applicable)",
  "error_details": "raw error message when applicable"
}

笔记：

  • 默认 User-Agent 如果没有提供，则注射(curl-mcp/<version>)；如果需要，可以通过标头覆盖。
  • response_type 默认为文本。使用 json 解析/漂亮打印JSON， binary 用于base64+内容类型/大小元数据（通过 response.content_type).
  • persist_session 为链式调用在每个主机的内存中保存Cookie； follow_redirects=false 允许您捕获重定向+设置Cookie； clear_session 在发出请求之前为主机擦除Cookie。
  • 允许在任何动词上使用Bodies（对于接受带Bodies的GET的API很有用）。

常见标题示例：

{
  "User-Agent": "curl-mcp/0.0.5",
  "Accept": "application/json",
  "Content-Type": "application/json"
}

🧪 集成测试

文件：

docs/integration-tests.json

包含人类和人工智能可读的集成场景，例如：

  • 简单GET
  • 后回声
  • 头部往返
  • 超时和错误处理
  • 重定向打开/关闭
  • Cookie+会话重用+清除
  • 二进制base64+内容类型
  • JSON解析回退
  • 笑话/猫/狗API
  • 美国国家航空航天局
  • 伦敦的天气数据

这些可以手动执行，也可以由MCP客户端/代理使用 curl_request.

📁 公共项目结构

packages/
  core-engine/      # HTTP engine (fetch wrapper, response shaping)
  mcp-stdio/        # stdio + Express HTTP transports exposing curl_request
docs/
  integration-tests.json

🖥 需求

  • Node.js 20或更高版本 （本地 fetch 支持）

🧭 路线图

  • 用于托管部署的HTTP身份验证选项（API密钥/承载器）
  • 轻量级指标/日志开关
  • 更多现成的吸烟/健康检查
  • 打包和发布更新

📄 许可证

麻省理工学院

相关 MCP