Curl MCP Server

Curl MCP Server

Un server MCP (Model Context Protocol) che fornisce strumenti HTTP/HTTPS completi utilizzando curl. Questo server consente di eseguire richieste HTTP con supporto per vari metodi di autenticazione, upload di file, download e comandi curl personalizzati.

Caratteristiche

• Richieste HTTP complete: GET, POST, PUT, PATCH, DELETE, HEAD
• Autenticazione multipla: Bearer Token, Basic Auth, Digest Auth, OAuth2, API Key, Custom Headers
• Upload e Download di file: Caricamento e scaricamento di file tramite HTTP
• Cookie Jar: Gestione persistente dei cookie per mantenere sessioni HTTP
• Comandi curl personalizzati: Esecuzione di comandi curl con controllo completo
• Test di autenticazione: Verifica delle credenziali di accesso
• Configurazione avanzata: Timeout, redirect, SSL/TLS, headers personalizzati

Installazione

1. Clona o scarica il progetto

1. Installa le dipendenze:

npm install

Installazione globale per utilizzo con npx

Per utilizzare il server con npx, puoi:

1. Installare localmente e linkare:

npm link

1. Pubblicare su npm (se vuoi condividerlo):

npm publish

1. Utilizzare direttamente da una cartella locale:

npm pack
npm install -g ./curl-mcp-server-1.0.0.tgz

Strumenti Disponibili

1. http_get

Esegue richieste HTTP GET

• Parametri: url, headers, auth, timeout, followRedirects, insecure, cookieJar

2. http_post

Esegue richieste HTTP POST

• Parametri: url, data, headers, auth, contentType, timeout, followRedirects, insecure, cookieJar

3. http_put

Esegue richieste HTTP PUT

• Parametri: url, data, headers, auth, contentType, timeout, followRedirects, insecure, cookieJar

4. http_delete

Esegue richieste HTTP DELETE

• Parametri: url, headers, auth, timeout, followRedirects, insecure, cookieJar

5. http_patch

Esegue richieste HTTP PATCH

• Parametri: url, data, headers, auth, contentType, timeout, followRedirects, insecure, cookieJar

6. http_head

Esegue richieste HTTP HEAD

• Parametri: url, headers, auth, timeout, followRedirects, insecure, cookieJar

7. curl_custom

Esegue comandi curl personalizzati

• Parametri: args (array di argomenti curl)

8. http_upload

Carica file tramite HTTP POST

• Parametri: url, filePath, fieldName, headers, auth, timeout, insecure, cookieJar

9. http_download

Scarica file tramite HTTP GET

• Parametri: url, outputPath, headers, auth, timeout, followRedirects, insecure, cookieJar

10. auth_test

Testa i metodi di autenticazione

• Parametri: url, auth, timeout, insecure

Metodi di Autenticazione Supportati

Bearer Token

{
  "type": "bearer",
  "token": "your-jwt-token"
}

Basic Authentication

{
  "type": "basic",
  "username": "user",
  "password": "password"
}

Digest Authentication

{
  "type": "digest",
  "username": "user",
  "password": "password"
}

OAuth2 Token

{
  "type": "oauth2",
  "token": "your-oauth2-token"
}

API Key in Header

{
  "type": "api_key",
  "key": "X-API-Key",
  "value": "your-api-key"
}

Custom Authorization

{
  "type": "custom",
  "header": "Authorization: Custom token123"
}

Cookie Jar per Gestione Sessioni

Il server supporta la gestione persistente dei cookie tramite cookie jar, utile per mantenere sessioni HTTP tra più richieste.

Utilizzo

Specifica il parametro cookieJar con il percorso di un file che verrà usato per salvare e caricare i cookie:

{
  "tool": "http_get",
  "arguments": {
    "url": "https://example.com/api/protected",
    "cookieJar": "/tmp/session-cookies.txt"
  }
}

Il cookie jar:

• Salva automaticamente i cookie ricevuti dal server
• Riutilizza i cookie nelle richieste successive
• Permette di mantenere sessioni autenticate senza dover passare token ad ogni richiesta
• È compatibile con il formato Netscape cookie file usato da curl

Configurazione per Client MCP

Per Claude Desktop (con npx)

Aggiungi questa configurazione al file di configurazione di Claude Desktop per utilizzare il server tramite npx:

{
  "mcpServers": {
    "curl-mcp": {
      "command": "npx",
      "args": [
        "curl-mcp-server"
      ]
    }
  }
}

Per Claude Desktop (locale)

Aggiungi questa configurazione al file di configurazione di Claude Desktop per utilizzare il server locale:

{
  "mcpServers": {
    "curl-mcp": {
      "command": "node",
      "args": ["e:\\MCP_servers\\curl-mcp\\index.js"],
      "env": {}
    }
  }
}

Per altri client MCP

Usa la configurazione seguente:

{
  "name": "curl-mcp-server",
  "version": "1.0.0",
  "command": "node",
  "args": ["percorso/assoluto/al/index.js"],
  "transport": "stdio"
}

Esempi di Utilizzo

Richiesta GET semplice

// Attraverso il client MCP
{
  "tool": "http_get",
  "arguments": {
    "url": "https://api.example.com/data"
  }
}

Richiesta POST con autenticazione Bearer

{
  "tool": "http_post",
  "arguments": {
    "url": "https://api.example.com/data",
    "data": "{\"name\": \"test\"}",
    "auth": {
      "type": "bearer",
      "token": "your-jwt-token"
    },
    "headers": {
      "Content-Type": "application/json"
    }
  }
}

Upload di file

{
  "tool": "http_upload",
  "arguments": {
    "url": "https://api.example.com/upload",
    "filePath": "/path/to/file.jpg",
    "fieldName": "image",
    "auth": {
      "type": "api_key",
      "key": "X-API-Key",
      "value": "your-api-key"
    }
  }
}

Comando curl personalizzato

{
  "tool": "curl_custom",
  "arguments": {
    "args": ["-X", "PATCH", "-H", "Content-Type: application/json", "-d", "{\"status\": \"active\"}", "https://api.example.com/users/123"]
  }
}

Risorse Disponibili

Il server fornisce risorse informative accessibili tramite:

• http://info/tools - Lista degli strumenti disponibili
• http://info/auth - Tipi di autenticazione supportati
• http://info/examples - Esempi di utilizzo dell'autenticazione

Avvio del Server

Modalità normale

npm start

Modalità sviluppo (con watch)

npm run dev

Requisiti di Sistema

• Node.js 18 o superiore
• curl installato e disponibile nel PATH del sistema
• Accesso di rete per le richieste HTTP/HTTPS

Sicurezza

• Tutti i comandi curl sono eseguiti in modo sicuro utilizzando spawn
• Supporto per SSL/TLS con opzione per connessioni insicure quando necessario
• Validazione degli input tramite schema Zod
• Gestione degli errori per prevenire crash del server

Troubleshooting

Errore "curl: command not found"

Assicurati che curl sia installato e disponibile nel PATH:

• Windows: Installa curl o usa Windows Subsystem for Linux
• macOS: curl è preinstallato
• Linux: sudo apt-get install curl (Ubuntu/Debian) o equivalente

Timeout delle richieste

Aumenta il valore del timeout nei parametri degli strumenti se necessario (default: 30 secondi per la maggior parte delle operazioni, 60 per upload, 300 per download).

Problemi SSL/TLS

Usa il parametro insecure: true per bypassare la verifica dei certificati SSL (solo per testing).

Licenza

MIT License - Vedi il file LICENSE per i dettagli.