curl-mcp

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

It provides a single tool:

curl_request

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

✨ 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)

▶️ 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:

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:

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

From CLI (

If curl-mcp is on your PATH (for example via Homebrew or npm), point your MCP client at it directly without using npm run:

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:

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):

🔍 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)

Output (schema overview)

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:

🧪 Integration Tests

The file:

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

🖥 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