Curl MCP Server
An MCP server that enables AI assistants to make HTTP requests and download files using curl, allowing them to interact with web APIs and content.
README Documentation
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