Execute cURL Request

Execute an HTTP request using cURL with structured parameters.

This tool provides a safe, structured way to make HTTP requests with common cURL options. It handles URL encoding, header formatting, and response processing automatically.

Args:

• url (string, required): The URL to request

• method (string): HTTP method - GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

• headers (object): HTTP headers as key-value pairs

• data (string): Request body for POST/PUT/PATCH requests

• form (object): Form data as key-value pairs (multipart/form-data)

• follow_redirects (boolean): Follow HTTP redirects (default: true)

• max_redirects (number): Maximum redirects to follow (0-50)

• insecure (boolean): Skip SSL verification (default: false)

• timeout (number): Request timeout in seconds (1-300, default: 30)

• user_agent (string): Custom User-Agent header (a browser-like default is sent automatically if not set; empty string disables)

• basic_auth (string): Basic auth as "username:password"

• bearer_token (string): Bearer token for Authorization header

• verbose (boolean): Include verbose request/response details

• include_headers (boolean): Include response headers in output

• compressed (boolean): Request compressed response (default: true)

• include_metadata (boolean): Wrap response in JSON with metadata

• jq_filter (string): JSON path filter to extract specific data

• max_result_size (number): Max bytes to return inline (default: 500KB, max: 1MB). Auto-saves to file when exceeded

• save_to_file (boolean): Force save response to temp file. Returns filepath instead of content

• output_dir (string): Custom directory to save files (overrides MCP_CURL_OUTPUT_DIR env var)

jq_filter Syntax:

• .key - Object property access

• .[n] or .n - Array index (non-negative only, e.g., .results.0)

• .[n:m] - Array slice from index n to m

• .["key"] - Bracket notation for special characters in keys

• .a,.b,.c - Multiple comma-separated paths (returns array of values, max 20)

jq_filter Validation:

• Unclosed quotes and brackets throw clear errors

• Leading zeros in indices rejected (use .0 not .00)

• Negative indices not supported (unlike real jq)

• Indices must be within safe integer range

Returns: The HTTP response body, or JSON with metadata if include_metadata is true: { "success": boolean, "exit_code": number, "response": string, "stderr": string (if present), "saved_to_file": boolean (if response was saved), "filepath": string (path to saved file) }

Examples:

• Simple GET: { "url": "https://api.example.com/data" }

• POST JSON: { "url": "https://api.example.com/users", "method": "POST", "headers": {"Content-Type": "application/json"}, "data": "{"name": "John"}" }

• With auth: { "url": "https://api.example.com/secure", "bearer_token": "your-token-here" }

• Extract field: { "url": "https://api.github.com/repos/octocat/hello-world", "jq_filter": ".name" }

• Multiple fields: { "url": "https://api.example.com/user", "jq_filter": ".name,.email,.id" }

• Dot notation: { "url": "https://api.example.com/items", "jq_filter": ".results.0.name" }

• Array slice: { "url": "https://api.example.com/items", "jq_filter": ".results[0:10]" }

• Custom output: { "url": "https://api.example.com/large", "save_to_file": true, "output_dir": "/path/to/dir" }

Error Handling:

• Returns error message if cURL fails or times out

• Exit code 0 indicates success

• Non-zero exit codes indicate various cURL errors

• Invalid JSON with jq_filter returns error with response preview

Temp File Lifecycle: Files saved with save_to_file or auto-save are:

• Stored in a secure temp directory (owner-only access: 0o700/0o600)

• Deleted on graceful server shutdown (SIGINT/SIGTERM)

• Orphaned files from crashed sessions are cleaned on next server start

• Check mcp-curl-* in system temp dir if files persist after crash