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

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.