Supabase MCP Server

Instructions

Implementation Reference

• src/index.ts:250-289 (handler)

  The main execution logic for the 'query_table' tool: validates input, constructs a Supabase query with schema, table, select columns, where conditions, limits to 25 rows, executes it, and returns JSON-stringified results.

  case "query_table": {
    if (!isValidQueryTableArgs(request.params.arguments)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Invalid query table arguments"
      );
    }
  
    const {
      schema = "public",
      table,
      select = "*",
      where = [],
    } = request.params.arguments;
  
    // Start the query builder
    let query = this.supabase
      .schema(schema)
      .from(table)
      .select(select)
      .limit(25);
  
    // Apply where conditions
    where.forEach((condition) => {
      query = this.applyWhereCondition(query, condition);
    });
  
    const { data, error } = await query;
  
    if (error) throw error;
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }

• src/index.ts:40-49 (schema)

  TypeScript interface defining the structure of input arguments for the query_table tool, including optional schema, required table, optional select, and where clauses.

  interface QueryTableArgs {
    schema?: string;
    table: string;
    select?: string;
    where?: {
      column: string;
      operator: WhereOperator;
      value: any;
    }[];
  }

• src/index.ts:175-230 (registration)

  Tool registration in the ListTools handler, providing the name, description, and detailed JSON schema for input validation.

    name: "query_table",
    description:
      "Query a specific table with schema selection and where clause support",
    inputSchema: {
      type: "object",
      properties: {
        schema: {
          type: "string",
          description: "Database schema (optional, defaults to public)",
        },
        table: {
          type: "string",
          description: "Name of the table to query",
        },
        select: {
          type: "string",
          description:
            "Comma-separated list of columns to select (optional, defaults to *)",
        },
        where: {
          type: "array",
          description: "Array of where conditions (optional)",
          items: {
            type: "object",
            properties: {
              column: {
                type: "string",
                description: "Column name",
              },
              operator: {
                type: "string",
                description: "Comparison operator",
                enum: [
                  "eq",
                  "neq",
                  "gt",
                  "gte",
                  "lt",
                  "lte",
                  "like",
                  "ilike",
                  "is",
                ],
              },
              value: {
                type: "any",
                description: "Value to compare against",
              },
            },
            required: ["column", "operator", "value"],
          },
        },
      },
      required: ["table"],
    },
  },

• src/index.ts:55-80 (helper)

  Type guard function to validate that tool arguments conform to the QueryTableArgs interface before execution.

  const isValidQueryTableArgs = (args: any): args is QueryTableArgs =>
    typeof args === "object" &&
    args !== null &&
    typeof args.table === "string" &&
    (args.schema === undefined || typeof args.schema === "string") &&
    (args.select === undefined || typeof args.select === "string") &&
    (args.where === undefined ||
      (Array.isArray(args.where) &&
        args.where.every(
          (w: any) =>
            typeof w === "object" &&
            w !== null &&
            typeof w.column === "string" &&
            typeof w.operator === "string" &&
            [
              "eq",
              "neq",
              "gt",
              "gte",
              "lt",
              "lte",
              "like",
              "ilike",
              "is",
            ].includes(w.operator)
        )));

• src/index.ts:131-159 (helper)

  Helper method to apply individual WHERE conditions to the Supabase query builder using the specified operator.

  private applyWhereCondition(
    query: any,
    condition: { column: string; operator: WhereOperator; value: any }
  ): any {
    switch (condition.operator) {
      case "eq":
        return query.eq(condition.column, condition.value);
      case "neq":
        return query.neq(condition.column, condition.value);
      case "gt":
        return query.gt(condition.column, condition.value);
      case "gte":
        return query.gte(condition.column, condition.value);
      case "lt":
        return query.lt(condition.column, condition.value);
      case "lte":
        return query.lte(condition.column, condition.value);
      case "like":
        return query.like(condition.column, condition.value);
      case "ilike":
        return query.ilike(condition.column, condition.value);
      case "is":
        return query.is(condition.column, condition.value);
      default:
        throw new McpError(
          ErrorCode.InvalidParams,
          `Unsupported operator: ${condition.operator}`
        );
    }