MCP Server for Curl
A Model Context Protocol (MCP) server that provides curl functionality, allowing AI assistants to make HTTP requests directly from their environment.
Features
- HTTP Methods: Support for GET, POST, PUT, DELETE requests
- File Downloads: Download files with curl
- Advanced Options: Custom headers, timeouts, redirects, and more
- JSON Support: Built-in JSON data handling for POST/PUT requests
- User Agent: Custom User-Agent string support
- Security: Safe subprocess execution with input validation
Installation
Method 1: NPM Installation (Recommended)
# Install globally
npm install -g @247arjun/mcp-curl
# Or install locally in your project
npm install @247arjun/mcp-curl
Method 2: From Source
# Clone the repository
git clone https://github.com/247arjun/mcp-curl.git
cd mcp-curl
# Install dependencies
npm install
# Build the project
npm run build
# Optional: Link globally
npm link
Method 3: Direct from GitHub
# Install directly from GitHub
npm install -g git+https://github.com/247arjun/mcp-curl.git
Configuration
Claude Desktop Setup
Add to your Claude Desktop configuration file:
Location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%/Claude/claude_desktop_config.json
Configuration:
{
"mcpServers": {
"mcp-curl": {
"command": "mcp-curl",
"args": []
}
}
}
Alternative: Using npx (no global install needed)
{
"mcpServers": {
"mcp-curl": {
"command": "npx",
"args": ["@247arjun/mcp-curl"]
}
}
}
Local Development Setup
{
"mcpServers": {
"mcp-curl": {
"command": "node",
"args": ["/absolute/path/to/mcp-curl/build/index.js"]
}
}
}
After adding the configuration, restart Claude Desktop to load the MCP server.
Available Tools
1. curl_get
Make HTTP GET requests.
Parameters:
url(string): The URL to make the GET request toheaders(array, optional): HTTP headers in the format 'Header: Value'timeout(number, optional): Request timeout in secondsfollow_redirects(boolean, optional): Whether to follow redirectsuser_agent(string, optional): Custom User-Agent string
Example:
{
"url": "https://api.example.com/data",
"headers": ["Authorization: Bearer token"],
"timeout": 30,
"follow_redirects": true,
"user_agent": "MyApp/1.0"
}
2. curl_post
Make HTTP POST requests with data.
Parameters:
url(string): The URL to make the POST request tojson_data(object, optional): JSON object to send as POST datadata(string, optional): Data to send in the POST request bodyheaders(array, optional): HTTP headerscontent_type(string, optional): Content-Type headertimeout(number, optional): Request timeout in secondsfollow_redirects(boolean, optional): Whether to follow redirects
Example:
{
"url": "https://api.example.com/data",
"json_data": {"key": "value"},
"headers": ["Content-Type: application/json"]
}
3. curl_put
Make HTTP PUT requests.
Parameters:
url(string): The URL to make the PUT request tojson_data(object, optional): JSON object to send as PUT datadata(string, optional): Data to send in the PUT request bodyheaders(array, optional): HTTP headerscontent_type(string, optional): Content-Type headertimeout(number, optional): Request timeout in secondsfollow_redirects(boolean, optional): Whether to follow redirects
Example:
{
"url": "https://api.example.com/data/123",
"data": "raw data",
"content_type": "text/plain"
}
4. curl_delete
Make HTTP DELETE requests.
Parameters:
url(string): The URL to make the DELETE request toheaders(array, optional): HTTP headerstimeout(number, optional): Request timeout in secondsfollow_redirects(boolean, optional): Whether to follow redirects
Example:
{
"url": "https://api.example.com/data/123",
"headers": ["Authorization: Bearer token"]
}
5. curl_download
Download files.
Parameters:
url(string): The URL of the file to downloadoutput_filename(string, optional): Output filenameresume(boolean, optional): Resume partial download if file existstimeout(number, optional): Request timeout in secondsfollow_redirects(boolean, optional): Whether to follow redirects
Example:
{
"url": "https://example.com/file.zip",
"output_filename": "downloaded_file.zip",
"resume": true
}
6. curl_advanced
Execute curl with custom arguments (advanced users).
Parameters:
args(array): Array of curl arguments (excluding 'curl' itself)
Example:
{
"args": ["-X", "PATCH", "-H", "Content-Type: application/json", "-d", "{\"status\":\"updated\"}", "https://api.example.com/items/1"]
}
Usage Examples
Make a GET request
{
"tool": "curl_get",
"url": "https://api.example.com/users",
"headers": ["Authorization: Bearer your-token"]
}
POST JSON data
{
"tool": "curl_post",
"url": "https://api.example.com/users",
"json_data": {
"name": "John Doe",
"email": "john@example.com"
}
}
Download a file
{
"tool": "curl_download",
"url": "https://example.com/file.zip",
"output_filename": "download.zip"
}
Development
Prerequisites
- Node.js 18.0.0 or higher
- npm package manager
- curl command-line tool
Building
npm run build
Testing
Test the server manually:
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node build/index.js
Run tests:
npm test
Linting
npm run lint
npm run lint:fix
Project Structure
mcp-curl/
├── src/
│ └── index.ts # Main server implementation
├── build/
│ └── index.js # Compiled JavaScript
├── test/
│ └── basic.test.js # Basic functionality tests
├── examples/
│ └── test-server.js # Example usage
├── .github/
│ └── workflows/
│ └── ci.yml # CI/CD pipeline
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
├── .eslintrc.json # ESLint configuration
├── LICENSE # MIT License
├── DEPLOYMENT.md # Deployment guide
├── CONTRIBUTING.md # Contribution guidelines
├── CHANGELOG.md # Version history
└── README.md # This file
Verification
Test that the server is working:
# Test the built server
node build/index.js
# Should show: "Curl MCP Server running on stdio"
# Press Ctrl+C to exit
Troubleshooting
Common Issues
-
"Command not found" error
- Ensure mcp-curl is installed globally:
npm install -g @247arjun/mcp-curl - Or use npx:
"command": "npx", "args": ["@247arjun/mcp-curl"]
- Ensure mcp-curl is installed globally:
-
"Permission denied" error
- Check file permissions:
chmod +x build/index.js - Rebuild the project:
npm run build
- Check file permissions:
-
MCP server not appearing in Claude
- Verify JSON syntax in configuration file
- Restart Claude Desktop completely
- Check that the command path is correct
-
"curl command not found"
- Install curl on your system (usually pre-installed on macOS/Linux)
- Windows users: Install via package manager or download from curl website
Debugging
Enable verbose logging by setting environment variable:
# For development
DEBUG=1 node build/index.js
# Test with sample input
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}}' | node build/index.js
Security Notes
- Input validation and sanitization for all curl arguments
- Restricted file operations in advanced mode
- Safe subprocess execution using spawn instead of shell
- No arbitrary shell command execution
- Input validation with Zod schemas