MCP Cloudflare DNS Server

Instructions

Implementation Reference

• src/index.ts:203-234 (handler)

  The main MCP tool handler for 'list_dns_records'. Configures API, fetches records via CloudflareApi.findDnsRecords, formats response text, handles empty results and errors.

  const handleListDnsRecords = async (args: { name?: string; type?: string }) => {
    try {
      if (!configureApiIfNeeded()) {
        return {
          content: [{ type: "text", text: "❌ Configuration incomplete. Please configure Cloudflare API Token and Zone ID first." }],
        };
      }
      
      const records = await CloudflareApi.findDnsRecords(args.name, args.type);
      
      if (records.length === 0) {
        return {
          content: [{ type: "text", text: "No DNS records found matching the criteria." }],
        };
      }
      
      const recordsText = records.map(record => 
        `🔹 ${record.name} (${record.type}) → ${record.content} [ID: ${record.id}]${record.proxied ? ' 🟠 Proxied' : ''}`
      ).join('\n');
      
      return {
        content: [{ 
          type: "text", 
          text: `✅ Found ${records.length} DNS record(s):\n\n${recordsText}`
        }],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `❌ Error listing DNS records: ${error instanceof Error ? error.message : 'Unknown error'}` }],
      };
    }
  };

• src/api.ts:196-229 (helper)

  Core API helper that calls Cloudflare DNS records endpoint with optional name/type filters, parses JSON response using Zod CloudflareApiResponse schema, returns DnsRecord[].

  findDnsRecords: async (name?: string, type?: string): Promise<DnsRecord[]> => {
    let endpoint = 'dns_records';
    const params = new URLSearchParams();
    
    if (name) params.append('name', name);
    if (type) params.append('type', type);
    
    if (params.toString()) {
      endpoint += `?${params.toString()}`;
    }
    
    const response = await api(endpoint);
    const rawData = await response.json();
    
    try {
      const data = CloudflareApiResponse.parse(rawData);
      
      if (!data.success) {
        throw new Error(`API Error: ${data.errors.map(e => e.message).join(', ')}`);
      }
      
      if (!data.result) {
        return [];
      }
      
      // Handle both array and single object results
      const records = Array.isArray(data.result) ? data.result : [data.result];
      return records.filter(record => record !== null);
    } catch (parseError) {
      console.error('API Response parsing failed:', parseError);
      console.error('Raw API Response:', JSON.stringify(rawData, null, 2));
      throw new Error(`Failed to parse API response: ${parseError instanceof Error ? parseError.message : 'Unknown error'}`);
    }
  },

• src/index.ts:49-66 (registration)

  Tool registration in ListTools handler: defines name, description, and input schema for 'list_dns_records'.

  {
    name: "list_dns_records",
    description: "List all DNS records for the configured zone",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "Filter by record name (optional)",
        },
        type: {
          type: "string",
          enum: ["A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "CAA", "PTR"],
          description: "Filter by record type (optional)",
        },
      },
    },
  },

• src/types.ts:27-48 (schema)

  Zod schema for Cloudflare API response parsing, used in findDnsRecords to validate and extract DNS records.

  export const CloudflareApiResponse = z.object({
    success: z.boolean(),
    errors: z.array(z.object({
      code: z.number(),
      message: z.string(),
    })),
    messages: z.array(z.object({
      code: z.number(),
      message: z.string(),
    })),
    result: z.union([
      z.array(CloudflareDnsRecord),
      CloudflareDnsRecord,
      z.null(),
    ]).optional(),
    result_info: z.object({
      page: z.number(),
      per_page: z.number(),
      count: z.number(),
      total_count: z.number(),
    }).optional(),
  });

• src/types.ts:8-25 (schema)

  Zod schema defining the structure of a Cloudflare DNS record, used for response validation.

  export const CloudflareDnsRecord = z.object({
    id: z.string(),
    zone_id: z.string().optional(),
    zone_name: z.string().optional(),
    name: z.string(),
    type: DnsRecordType,
    content: z.string(),
    proxied: z.boolean().optional(),
    ttl: z.number(),
    priority: z.number().optional(),
    created_on: z.string(),
    modified_on: z.string(),
    meta: z.object({
      auto_added: z.boolean().optional(),
      managed_by_apps: z.boolean().optional(),
      managed_by_argo_tunnel: z.boolean().optional(),
    }).optional(),
  });