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: MCP Toolkit

Installation

# Clone or create the project directory
mkdir curl-mcp-server
cd curl-mcp-server

# Install dependencies
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node tsx

# Create src directory and add the TypeScript code
mkdir src
# Place the server code in src/index.ts

# Build the project
npm run build

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:

{
  "url": "https://api.github.com/user",
  "headers": ["Authorization: token YOUR_TOKEN"],
  "timeout": 15
}

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:

{
  "url": "https://api.example.com/data",
  "data": "{\"key\": \"value\"}",
  "content_type": "application/json",
  "headers": ["Authorization: Bearer TOKEN"]
}

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:

{
  "args": ["-X", "PUT", "-H", "Content-Type: application/json", "-d", "{\"status\": \"updated\"}", "https://api.example.com/resource/123"],
  "timeout": 20
}

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:

{
  "url": "https://example.com/file.pdf",
  "output_file": "/tmp/downloaded_file.pdf"
}

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

# Through MCP client
{
  "tool": "curl_get",
  "arguments": {
    "url": "https://httpbin.org/get"
  }
}

POST with JSON Data

{
  "tool": "curl_post",
  "arguments": {
    "url": "https://httpbin.org/post",
    "data": "{\"message\": \"hello world\"}",
    "content_type": "application/json"
  }
}

Custom Headers

{
  "tool": "curl_get",
  "arguments": {
    "url": "https://api.github.com/user",
    "headers": [
      "Authorization: token ghp_xxxxxxxxxxxx",
      "User-Agent: MyApp/1.0"
    ]
  }
}

Running the Server

# Development mode
npm run dev

# Production mode
npm run build
npm start

Integration with Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "curl": {
      "command": "node",
      "args": ["/path/to/curl-mcp-server/build/index.js"]
    }
  }
}

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.