Curl MCP Server

A Model Context Protocol (MCP) server that provides secure curl command execution capabilities through terminal shell integration.

Features

• GET Requests: Execute HTTP GET requests with custom headers

• POST Requests: Send POST data with configurable content types

• Custom Commands: Execute custom curl commands with safety restrictions

• File Downloads: Download files and get metadata

• Security: Built-in protections against dangerous operations

• Timeouts: Configurable request timeouts (max 30 seconds)

• Output Limits: Protection against excessive output size

Related MCP server: Command Executor MCP Server

Installation

Prerequisites

• Node.js 18+

• curl command available in PATH

• TypeScript compiler

Available Tools

1. curl_get

Execute HTTP GET requests.

Parameters:

• url (required): The URL to request

• headers (optional): Array of headers in "Key: Value" format

• timeout (optional): Timeout in seconds (default: 10, max: 30)

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

Example:

2. curl_post

Execute HTTP POST requests.

Parameters:

• url (required): The URL to request

• data (required): POST data to send

• content_type (optional): Content-Type header (default: "application/json")

• headers (optional): Array of additional headers

• timeout (optional): Timeout in seconds (default: 10, max: 30)

Example:

3. curl_custom

Execute custom curl commands with full control.

Parameters:

• args (required): Array of curl arguments (without the 'curl' command)

• timeout (optional): Timeout in seconds (default: 10, max: 30)

Example:

4. curl_download

Download files and get metadata.

Parameters:

• url (required): The URL to download from

• output_file (optional): Output file path

• timeout (optional): Timeout in seconds (default: 30, max: 30)

Example:

Security Features

• URL Validation: Only HTTP and HTTPS URLs allowed

• Argument Filtering: Dangerous curl flags are blocked

• Output Limits: Maximum 1MB output size to prevent memory issues

• Timeouts: All requests have configurable timeouts

• Safe Defaults: Reasonable default values for all parameters

Blocked Operations

For security, the following curl operations are restricted:

• File uploads (--upload-file, --form)

• Config file loading (--config)

• Unrestricted file output (controlled through specific tools)

• Binary data uploads

• Trace file generation

Usage Examples

Basic GET Request

POST with JSON Data

Custom Headers

Running the Server

Integration with Claude Desktop

Add to your Claude Desktop configuration:

Error Handling

The server provides detailed error messages for:

• Invalid URLs

• Timeout errors

• Curl execution failures

• Output size limits exceeded

• Security violations

Limitations

• Maximum request timeout: 30 seconds

• Maximum output size: 1MB

• Only HTTP/HTTPS protocols supported

• Certain curl flags are blocked for security

Contributing

Feel free to submit issues and enhancement requests. Make sure to test any changes thoroughly, especially security-related modifications.

License

MIT License - see LICENSE file for details.