JUHE API Marketplace
247arjun avatar
MCP Server

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.

0
GitHub Stars
8/23/2025
Last Updated
MCP Server Configuration
1{
2 "name": "mcp-curl",
3 "command": "mcp-curl",
4 "args": []
5}
JSON5 lines

README Documentation

MCP Server for Curl

npm version

A Model Context Protocol (MCP) server that provides curl functionality, allowing AI assistants to make HTTP requests directly from their environment.

Curl Server MCP server

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 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"
}

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

  • 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

Quick Install

Quick Actions

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source