curl-mcp

curl-mcp is an open-source HTTP/cURL tool for the Model Context Protocol (MCP).

It provides a single tool:

curl_request – a structured HTTP client designed for AI assistants and MCP-aware development tools.

This server is intended for use with any MCP-compatible client, such as:

• ChatGPT Desktop
• Roo Code
• Cursor
• Cline
• Continue.dev
• Custom MCP agents

No client-specific configuration examples are included here — each MCP client provides its own method for adding local MCP servers.
You simply run curl-mcp, then register it inside your client.

---

✨ Features

• 🔌 MCP stdio server
  Run locally and expose the curl_request tool to any MCP client.

• 🧰 Full HTTP support
  Supports GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

• 🧱 Structured JSON responses
  Includes:

  • HTTP status code
  • status text
  • headers
  • raw text body
  • timing metrics
  • total size
  • simple advice messages

• 🕒 Timeout & network error handling
  Uses AbortController under the hood.

• 🧪 Integration-test friendly
  Includes a self-describing JSON test file for humans or AI agents.

---

📦 Installation (from source)

npm install
npm run build

---

▶️ Running the MCP server

You can run curl-mcp either directly from this source repo, or via an installed CLI on your PATH.

From source (local clone)

From the root of your local curl-mcp clone:

npm run dev:stdio

This launches the curl-mcp MCP server on stdio.
Configure your MCP client to run that same command in the repo directory.
Some clients let you set the working directory explicitly; others work better if you pass a --prefix pointing at your clone.
For example, an mcpServers JSON block might look like:

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

Make sure the working directory for the command is the root of your local curl-mcp clone.

From CLI (curl-mcp on PATH)

If you have installed the curl-mcp CLI so that it is available on your PATH
(for example via Homebrew, npm, or another package manager), you can point your MCP client at it directly without using npm run:

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

Important:
MCP clients each have their own method of adding a local MCP server and choosing the working directory.
Use the examples above as a guide, but refer to your client’s documentation for the exact configuration format.

---

🛠 Tool: curl_request

Input (schema overview)

{
  "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; keep cookies in-memory for chained calls)",
  "follow_redirects": "boolean (optional; default true)"
}

Output (schema overview)

{
  "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": { ... },
    "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"
}

Notes:

• Default User-Agent is injected if none is provided (curl-mcp/<version>); override via headers if needed.
• response_type defaults to text. Use json to parse/pretty-print JSON, binary for base64 + content-type/size metadata.
• persist_session is opt-in and keeps cookies in-memory for chained calls; follow_redirects can be turned off to capture redirect responses.

---

🧪 Integration Tests

The file:

docs/integration-tests.json

contains human- and AI-readable integration scenarios such as:

• simple GET
• POST echo
• header round-trip
• timeout behaviour
• error handling
• joke/cat/dog APIs
• NASA APOD
• Weather data for London

These can be executed manually or by an MCP client/agent using curl_request.

---

📁 Public Project Structure

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

---

🖥 Requirements

• Node.js 20 or later (native fetch support)

---

🧭 Roadmap

• Optional binary/base64 response mode
• Optional JSON parse mode
• Richer advice metadata
• Simple test runner script
• Packaging for npm / Homebrew

---

📄 License

MIT