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+
curlcommand available in PATH- TypeScript compiler
Available Tools
1. curl_get
Execute HTTP GET requests.
Parameters:
url(required): The URL to requestheaders(optional): Array of headers in "Key: Value" formattimeout(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 requestdata(required): POST data to sendcontent_type(optional): Content-Type header (default: "application/json")headers(optional): Array of additional headerstimeout(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 fromoutput_file(optional): Output file pathtimeout(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.