README.md•4.88 kB
# 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.