Curl MCP Server

Instructions

Implementation Reference

• src/index.ts:143-208 (handler)

  The handler function for the 'curl_post' tool. It constructs the curl command line arguments based on the input parameters (URL, data/JSON, headers, etc.), calls the shared executeCurl helper to run the command, and formats the stdout/stderr/output as text content.

  async ({ url, data, json_data, headers, content_type, follow_redirects, timeout }) => {
    const args = ['curl'];
    
    // Add the URL
    args.push(url);
    
    // Add POST method
    args.push('-X', 'POST');
    
    // Handle data
    if (json_data) {
      args.push('-d', JSON.stringify(json_data));
      if (!content_type) {
        content_type = 'application/json';
      }
    } else if (data) {
      args.push('-d', data);
    }
    
    // Add content type header
    if (content_type) {
      args.push('-H', `Content-Type: ${content_type}`);
    }
    
    // Add additional headers if provided
    if (headers && headers.length > 0) {
      headers.forEach(header => {
        args.push('-H', header);
      });
    }
    
    // Add follow redirects option
    if (follow_redirects) {
      args.push('-L');
    }
    
    // Add timeout if provided
    if (timeout) {
      args.push('--max-time', timeout.toString());
    }
    
    // Include response headers in output
    args.push('-i');
    
    try {
      const result = await executeCurl(args);
      
      return {
        content: [
          {
            type: "text",
            text: `Exit Code: ${result.exitCode}\n\nResponse:\n${result.stdout}${result.stderr ? `\n\nErrors:\n${result.stderr}` : ''}`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error executing curl: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
      };
    }
  }

• src/index.ts:134-142 (schema)

  Zod input schema defining the parameters accepted by the curl_post tool.

  {
    url: z.string().describe("The URL to make the POST request to"),
    data: z.string().optional().describe("Data to send in the POST request body"),
    json_data: z.record(z.any()).optional().describe("JSON object to send as POST data"),
    headers: z.array(z.string()).optional().describe("Optional HTTP headers in the format 'Header: Value'"),
    content_type: z.string().optional().describe("Content-Type header (will be added automatically for JSON data)"),
    follow_redirects: z.boolean().optional().default(false).describe("Whether to follow redirects"),
    timeout: z.number().optional().describe("Request timeout in seconds"),
  },

• src/index.ts:131-209 (registration)

  The server.tool call that registers the 'curl_post' tool with name, description, input schema, and handler function.

  server.tool(
    "curl_post",
    "Make an HTTP POST request using curl",
    {
      url: z.string().describe("The URL to make the POST request to"),
      data: z.string().optional().describe("Data to send in the POST request body"),
      json_data: z.record(z.any()).optional().describe("JSON object to send as POST data"),
      headers: z.array(z.string()).optional().describe("Optional HTTP headers in the format 'Header: Value'"),
      content_type: z.string().optional().describe("Content-Type header (will be added automatically for JSON data)"),
      follow_redirects: z.boolean().optional().default(false).describe("Whether to follow redirects"),
      timeout: z.number().optional().describe("Request timeout in seconds"),
    },
    async ({ url, data, json_data, headers, content_type, follow_redirects, timeout }) => {
      const args = ['curl'];
      
      // Add the URL
      args.push(url);
      
      // Add POST method
      args.push('-X', 'POST');
      
      // Handle data
      if (json_data) {
        args.push('-d', JSON.stringify(json_data));
        if (!content_type) {
          content_type = 'application/json';
        }
      } else if (data) {
        args.push('-d', data);
      }
      
      // Add content type header
      if (content_type) {
        args.push('-H', `Content-Type: ${content_type}`);
      }
      
      // Add additional headers if provided
      if (headers && headers.length > 0) {
        headers.forEach(header => {
          args.push('-H', header);
        });
      }
      
      // Add follow redirects option
      if (follow_redirects) {
        args.push('-L');
      }
      
      // Add timeout if provided
      if (timeout) {
        args.push('--max-time', timeout.toString());
      }
      
      // Include response headers in output
      args.push('-i');
      
      try {
        const result = await executeCurl(args);
        
        return {
          content: [
            {
              type: "text",
              text: `Exit Code: ${result.exitCode}\n\nResponse:\n${result.stdout}${result.stderr ? `\n\nErrors:\n${result.stderr}` : ''}`,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error executing curl: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
        };
      }
    }
  );

• src/index.ts:23-62 (helper)

  Shared helper function used by curl_post (and other curl tools) to safely spawn a child curl process, capture output streams, and return stdout, stderr, and exit code.

  async function executeCurl(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
    return new Promise((resolve) => {
      // Ensure we're only calling curl with safe arguments
      if (!args.includes('curl')) {
        args.unshift('curl');
      }
      
      const child = spawn('curl', args.slice(1), {
        stdio: ['pipe', 'pipe', 'pipe'],
        shell: false,
      });
  
      let stdout = '';
      let stderr = '';
  
      child.stdout.on('data', (data) => {
        stdout += data.toString();
      });
  
      child.stderr.on('data', (data) => {
        stderr += data.toString();
      });
  
      child.on('close', (code) => {
        resolve({
          stdout,
          stderr,
          exitCode: code || 0,
        });
      });
  
      child.on('error', (error) => {
        resolve({
          stdout: '',
          stderr: error.message,
          exitCode: 1,
        });
      });
    });
  }