# 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):
```bash
npm install
npm run dev:stdio # stdio transport
npm run dev:http # HTTP transport (default: http://localhost:3000/mcp)
```
- From CLI (installed):
```bash
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)
```bash
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:
```bash
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:
```json
{
"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`:
```json
{
"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:
```bash
# 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`):
```json
{
"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)
```json
{
"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)
```json
{
"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:
```json
{
"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
```text
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
