Cloudflare D1 Database MCP Server

Instructions

Implementation Reference

• src/client.ts:17-39 (handler)

  Core handler function in D1Client that executes the SQL query by making a POST request to the Cloudflare D1 API endpoint.

  async executeQuery(sql: string, bindings?: unknown[]): Promise<D1QueryResult> {
    const url = `${CLOUDFLARE_API_BASE}/accounts/${this.config.accountId}/d1/database/${this.config.databaseId}/raw`;
  
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${this.config.apiToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        sql,
        bindings,
      }),
    });
  
    if (!response.ok) {
      const text = await response.text();
      throw new Error(`Cloudflare D1 request failed with status ${response.status}: ${text}`);
    }
  
    const data = (await response.json()) as D1QueryResult;
    return data;
  }

• src/server.ts:68-82 (handler)

  MCP tool dispatch handler in server that parses arguments and delegates to D1Client.executeQuery, then formats the result as MCP content.

  if (name === "d1_query") {
    const { sql, bindings } = args as {
      sql: string;
      bindings?: unknown[];
    };
    
    const result = await client.executeQuery(sql, bindings);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2)
        }
      ]
    };

• src/server.ts:29-50 (registration)

  Tool registration in the listTools response, including name, description, and input schema.

  {
    name: "d1_query",
    description: "Run a SQL query against the configured Cloudflare D1 database.",
    inputSchema: {
      type: "object",
      properties: {
        sql: {
          type: "string",
          description: "The SQL statement to execute."
        },
        bindings: {
          type: "array",
          description: "Optional positional bindings for the SQL statement.",
          items: {
            type: ["string", "number", "boolean", "null"]
          }
        }
      },
      required: ["sql"]
    }
  },
  {

• src/client.ts:7-12 (schema)

  Type definition for the result returned by Cloudflare D1 API queries.

  export interface D1QueryResult {
    success: boolean;
    result?: unknown;
    errors?: Array<{ code: number; message: string }>;
    messages?: Array<{ code: number; message: string }>;
  }