MCP Curl

🚀 MCP Server for Curl

The MCP Server for Curl is a Model Context Protocol (MCP) server that offers curl functionality. It enables AI assistants to directly make HTTP requests from their environment, enhancing their data - fetching capabilities.

🚀 Quick Start

The MCP Server for Curl allows AI assistants to perform HTTP requests. To get started, you can install it via different methods as described in the installation section and configure it according to your needs.

✨ Features

• HTTP Methods: Supports GET, POST, PUT, DELETE requests.
• File Downloads: Allows downloading files with curl.
• Advanced Options: Provides custom headers, timeouts, redirects, and more.
• JSON Support: Has built - in JSON data handling for POST/PUT requests.
• User Agent: Supports custom User - Agent strings.
• Security: Ensures 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

📚 Documentation

Configuration

Claude Desktop Setup

Add the following 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 to.
• headers (array, optional): HTTP headers in the format 'Header: Value'.
• timeout (number, optional): Request timeout in seconds.
• follow_redirects (boolean, optional): Whether to follow redirects.
• user_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 to.
• json_data (object, optional): JSON object to send as POST data.
• data (string, optional): Data to send in the POST request body.
• headers (array, optional): HTTP headers.
• content_type (string, optional): Content - Type header.
• timeout (number, optional): Request timeout in seconds.
• follow_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 to.
• json_data (object, optional): JSON object to send as PUT data.
• data (string, optional): Data to send in the PUT request body.
• headers (array, optional): HTTP headers.
• content_type (string, optional): Content - Type header.
• timeout (number, optional): Request timeout in seconds.
• follow_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 to.
• headers (array, optional): HTTP headers.
• timeout (number, optional): Request timeout in seconds.
• follow_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 download.
• output_filename (string, optional): Output filename.
• resume (boolean, optional): Resume partial download if file exists.
• timeout (number, optional): Request timeout in seconds.
• follow_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"
}

🔧 Technical Details

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

1. "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"]
2. "Permission denied" error
   • Check file permissions: chmod +x build/index.js
   • Rebuild the project: npm run build
3. MCP server not appearing in Claude
   • Verify JSON syntax in configuration file
   • Restart Claude Desktop completely
   • Check that the command path is correct
4. "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

• Performs input validation and sanitization for all curl arguments.
• Has restricted file operations in advanced mode.
• Ensures safe subprocess execution using spawn instead of shell.
• Does not allow arbitrary shell command execution.
• Uses Zod schemas for input validation.

📄 License

This project is licensed under the MIT License.