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 transports
  Stdio for local dev and an Express-based HTTP server for hosted clients.

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

• 🧱 Structured responses
  Status, headers, content-type, timing, size, body (text/pretty JSON/base64), advice.

• 🍪 Session & redirect control
  In-memory cookie jar per host (persist_session), follow_redirects toggle, clear_session helper.

• 🕒 Timeout & network handling
  Abort controller with error typing: timeout, DNS, connect, SSL, generic network.

• 🧪 Integration-test friendly
  Self-describing JSON scenarios in docs/integration-tests.json.

🚀 Quick Start

• From source (local clone):

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

• From CLI (installed):

  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)
  

Then point your MCP client at the command you use (see configs below).

📦 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 curl-mcp is on your PATH (for example via Homebrew or npm), 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.

HTTP transport (Express)

Start the HTTP server:

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

Port and hardening (optional):

• Port: defaults to 3000; override with PORT or MCP_PORT (e.g., PORT=3400 npm run dev:http).
• MCP client config should match the server port, e.g. "url": "http://localhost:3400/mcp".
• If the port is in use, pick another free port and reflect it in the URL (some clients let you set host/port separately; otherwise include the port in the URL).
• Auth/allowlist (default: off). Opt in via env vars:
  • MCP_REQUIRE_KEY=true and MCP_API_KEYS=key1,key2 (checks Authorization: Bearer <key> or X-API-Key)
  • MCP_ALLOWED_HOSTS=host:port,otherhost:port (Host header check)
  • MCP_ALLOWED_ORIGINS=https://yourapp.com (Origin check + CORS allowlist) If unset, the server stays open for local/dev use.

Point your MCP client at the HTTP endpoint (default http://localhost:3000/mcp):

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

🔍 Smoke test (HTTP)

1. Start the HTTP server: npm run dev:http (or curl-mcp --http).
2. Run the smoke script: npm run smoke:http (set MCP_URL to override the endpoint).
3. You should see a one-line summary with the returned status/timing.

🛠 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; 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)"
}

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

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 (exposed via response.content_type).
• persist_session keeps cookies in-memory per host for chained calls; follow_redirects=false lets you capture the redirect + Set-Cookie; clear_session wipes cookies for the host before issuing the request.
• Bodies are allowed on any verb (useful for APIs that accept GET with bodies).

Common headers example:

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

🧪 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 and error handling
• redirects on/off
• cookies + session reuse + clearing
• binary base64 + content-type
• JSON parse fallback
• 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 + Express HTTP transports exposing curl_request
docs/
  integration-tests.json

🖥 Requirements

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

🧭 Roadmap

• HTTP auth options (API key/bearer) for hosted deployments
• Lightweight metrics/logging switch
• More ready-made smoke/health checks
• Packaging and publishing updates

📄 License

MIT