What is Curl Mcp Server

curl-mcp-server is a Model Context Protocol (MCP) server that enables secure execution of curl commands through terminal shell integration.

Use cases

Use cases include fetching data from APIs, sending data to servers, downloading files securely, and integrating curl commands into automated workflows.

How to use

To use curl-mcp-server, clone the project, install the necessary dependencies, and run the server using Node.js. You can execute GET and POST requests with customizable parameters.

Key features

Key features include executing GET and POST requests, custom command execution with safety restrictions, file downloads, built-in security protections, configurable timeouts, and output limits.

Where to use

curl-mcp-server can be used in web development, API testing, and automation tasks where secure curl command execution is required.

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.