# 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

```bash
# 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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
```bash
# Through MCP client
{
  "tool": "curl_get",
  "arguments": {
    "url": "https://httpbin.org/get"
  }
}
```

### POST with JSON Data
```bash
{
  "tool": "curl_post",
  "arguments": {
    "url": "https://httpbin.org/post",
    "data": "{\"message\": \"hello world\"}",
    "content_type": "application/json"
  }
}
```

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

## Running the Server

```bash
# Development mode
npm run dev

# Production mode
npm run build
npm start
```

## Integration with Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "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.