Curl MCP Server

Instructions

Implementation Reference

• src/index.ts:75-127 (handler)

  The handler function for the curl_get tool. It constructs the curl command arguments based on the provided parameters (url, headers, etc.) and executes it using the executeCurl helper, returning the response or error.

  async ({ url, headers, follow_redirects, timeout, user_agent }) => {
    const args = ['curl'];
    
    // Add the URL
    args.push(url);
    
    // Add 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());
    }
    
    // Add custom user agent if provided
    if (user_agent) {
      args.push('-A', user_agent);
    }
    
    // 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:69-74 (schema)

  Zod schema defining the input parameters for the curl_get tool.

    url: z.string().describe("The URL to make the GET request to"),
    headers: z.array(z.string()).optional().describe("Optional HTTP headers in the format 'Header: Value'"),
    follow_redirects: z.boolean().optional().default(false).describe("Whether to follow redirects"),
    timeout: z.number().optional().describe("Request timeout in seconds"),
    user_agent: z.string().optional().describe("Custom User-Agent string"),
  },

• src/index.ts:65-128 (registration)

  Registration of the curl_get tool using server.tool(), including name, description, schema, and handler function.

  server.tool(
    "curl_get",
    "Make an HTTP GET request using curl",
    {
      url: z.string().describe("The URL to make the GET request to"),
      headers: z.array(z.string()).optional().describe("Optional HTTP headers in the format 'Header: Value'"),
      follow_redirects: z.boolean().optional().default(false).describe("Whether to follow redirects"),
      timeout: z.number().optional().describe("Request timeout in seconds"),
      user_agent: z.string().optional().describe("Custom User-Agent string"),
    },
    async ({ url, headers, follow_redirects, timeout, user_agent }) => {
      const args = ['curl'];
      
      // Add the URL
      args.push(url);
      
      // Add 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());
      }
      
      // Add custom user agent if provided
      if (user_agent) {
        args.push('-A', user_agent);
      }
      
      // 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)

  Helper function executeCurl that safely spawns a curl child process, captures output streams and exit code. Used by all curl tools including curl_get.

  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,
        });
      });
    });
  }