metabase-agent-mcp-server 0.1.0

package/src/index.ts

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { MetabaseClient } from "./metabase-client.js";
+
+const METABASE_URL = process.env.METABASE_URL;
+const METABASE_API_KEY = process.env.METABASE_API_KEY;
+
+if (!METABASE_URL || !METABASE_API_KEY) {
+  console.error(
+    "Required environment variables: METABASE_URL, METABASE_API_KEY",
+  );
+  process.exit(1);
+}
+
+const client = new MetabaseClient({
+  url: METABASE_URL,
+  apiKey: METABASE_API_KEY,
+});
+
+const server = new McpServer({
+  name: "metabase-agent",
+  version: "0.1.0",
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type ToolResult = {
+  content: { type: "text"; text: string }[];
+  isError?: boolean;
+};
+
+async function handleToolCall<T>(
+  fn: () => Promise<T>,
+  format: (result: T) => string,
+): Promise<ToolResult> {
+  try {
+    const result = await fn();
+    return { content: [{ type: "text", text: format(result) }] };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: msg }], isError: true };
+  }
+}
+
+const json = (v: unknown) => JSON.stringify(v, null, 2);
+
+// ---------------------------------------------------------------------------
+// Tool: search
+// ---------------------------------------------------------------------------
+server.tool(
+  "search",
+  "Search for tables and metrics in Metabase. Supports term-based and semantic search queries. Results are ranked using Reciprocal Rank Fusion when both query types are provided.",
+  {
+    term_queries: z
+      .array(z.string().min(1))
+      .optional()
+      .describe("Term-based search queries"),
+    semantic_queries: z
+      .array(z.string().min(1))
+      .optional()
+      .describe("Semantic search queries"),
+  },
+  async ({ term_queries, semantic_queries }) =>
+    handleToolCall(
+      () => client.search({ term_queries, semantic_queries }),
+      json,
+    ),
+);
+
+// ---------------------------------------------------------------------------
+// Tool: get_table
+// ---------------------------------------------------------------------------
+server.tool(
+  "get_table",
+  "Get details for a table including fields, related tables, metrics, measures, and segments.",
+  {
+    id: z.number().int().min(1).describe("Table ID"),
+    with_fields: z
+      .boolean()
+      .optional()
+      .describe("Include table fields (default: true)"),
+    with_field_values: z
+      .boolean()
+      .optional()
+      .describe("Include sample field values (default: true)"),
+    with_related_tables: z
+      .boolean()
+      .optional()
+      .describe("Include related tables via FK (default: true)"),
+    with_metrics: z
+      .boolean()
+      .optional()
+      .describe("Include metrics associated with this table (default: true)"),
+    with_measures: z
+      .boolean()
+      .optional()
+      .describe("Include reusable measure definitions (default: false)"),
+    with_segments: z
+      .boolean()
+      .optional()
+      .describe("Include predefined filter segments (default: false)"),
+  },
+  async (args) =>
+    handleToolCall(
+      () =>
+        client.getTable(args.id, {
+          withFields: args.with_fields,
+          withFieldValues: args.with_field_values,
+          withRelatedTables: args.with_related_tables,
+          withMetrics: args.with_metrics,
+          withMeasures: args.with_measures,
+          withSegments: args.with_segments,
+        }),
+      json,
+    ),
+);
+
+// ---------------------------------------------------------------------------
+// Tool: get_metric
+// ---------------------------------------------------------------------------
+server.tool(
+  "get_metric",
+  "Get details for a metric including its queryable dimensions and segments.",
+  {
+    id: z.number().int().min(1).describe("Metric ID"),
+    with_queryable_dimensions: z
+      .boolean()
+      .optional()
+      .describe("Include queryable dimension fields (default: true)"),
+    with_field_values: z
+      .boolean()
+      .optional()
+      .describe("Include sample field values for dimensions (default: true)"),
+    with_default_temporal_breakout: z
+      .boolean()
+      .optional()
+      .describe(
+        "Include default time dimension for temporal breakouts (default: true)",
+      ),
+    with_segments: z
+      .boolean()
+      .optional()
+      .describe("Include predefined filter segments (default: false)"),
+  },
+  async (args) =>
+    handleToolCall(
+      () =>
+        client.getMetric(args.id, {
+          withQueryableDimensions: args.with_queryable_dimensions,
+          withFieldValues: args.with_field_values,
+          withDefaultTemporalBreakout: args.with_default_temporal_breakout,
+          withSegments: args.with_segments,
+        }),
+      json,
+    ),
+);
+
+// ---------------------------------------------------------------------------
+// Tool: get_field_values
+// ---------------------------------------------------------------------------
+server.tool(
+  "get_field_values",
+  "Get statistics and sample values for a specific field. Useful for understanding data distribution, valid filter values, and field characteristics.",
+  {
+    entity_type: z
+      .enum(["table", "metric"])
+      .describe("Whether the field belongs to a table or metric"),
+    entity_id: z.number().int().min(1).describe("Table or metric ID"),
+    field_id: z
+      .string()
+      .min(1)
+      .describe(
+        "Field ID (format: 't<id>-<index>' for table fields, 'c<id>-<index>' for metric fields)",
+      ),
+  },
+  async ({ entity_type, entity_id, field_id }) =>
+    handleToolCall(
+      () => client.getFieldValues(entity_type, entity_id, field_id),
+      json,
+    ),
+);
+
+// ---------------------------------------------------------------------------
+// Shared schemas for query construction
+// ---------------------------------------------------------------------------
+
+const FilterSchema = z.union([
+  z.object({ segment_id: z.number().int() }).describe("Segment filter"),
+  z
+    .object({
+      field_id: z.string(),
+      operation: z.string(),
+      value: z.any().optional(),
+      values: z.array(z.any()).optional(),
+      bucket: z.string().optional(),
+    })
+    .describe("Field filter"),
+]);
+
+const GroupBySchema = z.object({
+  field_id: z.string(),
+  field_granularity: z
+    .enum([
+      "minute",
+      "hour",
+      "day",
+      "week",
+      "month",
+      "quarter",
+      "year",
+      "day-of-week",
+    ])
+    .nullable()
+    .optional(),
+});
+
+const FieldRefSchema = z.object({
+  field_id: z.string(),
+  bucket: z.string().optional(),
+});
+
+const OrderBySchema = z.object({
+  field: FieldRefSchema,
+  direction: z.enum(["asc", "desc"]),
+});
+
+const AggregationSchema = z.union([
+  z.object({
+    function: z.literal("count"),
+    sort_order: z.enum(["asc", "desc"]).nullable().optional(),
+  }),
+  z.object({
+    field_id: z.string(),
+    function: z.enum(["avg", "count-distinct", "max", "min", "sum"]),
+    sort_order: z.enum(["asc", "desc"]).nullable().optional(),
+  }),
+  z.object({
+    measure_id: z.number().int(),
+    sort_order: z.enum(["asc", "desc"]).nullable().optional(),
+  }),
+]);
+
+// ---------------------------------------------------------------------------
+// Tool: run_query
+// ---------------------------------------------------------------------------
+server.tool(
+  "run_query",
+  `Construct and execute a query against Metabase, returning results directly.
+
+For tables: supports filters, fields, aggregations, group_by, order_by, limit.
+For metrics: supports filters, group_by (aggregation is defined by the metric).
+
+Provide EITHER table_id OR metric_id, not both.
+Row limits: 2000 for simple queries, 10000 for aggregated queries.`,
+  {
+    table_id: z
+      .number()
+      .int()
+      .min(1)
+      .optional()
+      .describe("Table ID (mutually exclusive with metric_id)"),
+    metric_id: z
+      .number()
+      .int()
+      .min(1)
+      .optional()
+      .describe("Metric ID (mutually exclusive with table_id)"),
+    filters: z
+      .array(FilterSchema)
+      .optional()
+      .describe("Filter conditions to apply"),
+    fields: z
+      .array(FieldRefSchema)
+      .optional()
+      .describe(
+        "Specific fields to select (omit for all fields, table queries only)",
+      ),
+    aggregations: z
+      .array(AggregationSchema)
+      .optional()
+      .describe(
+        "Aggregation functions: count, avg, sum, min, max, count-distinct, or measure_id (table queries only)",
+      ),
+    group_by: z
+      .array(GroupBySchema)
+      .optional()
+      .describe("Fields to group by, with optional temporal granularity"),
+    order_by: z
+      .array(OrderBySchema)
+      .optional()
+      .describe(
+        "Order by fields. To order by aggregation, use sort_order on the aggregation instead (table queries only)",
+      ),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .optional()
+      .describe("Maximum rows to return (table queries only)"),
+  },
+  async (args) => {
+    try {
+      const constructed = await client.constructQuery(
+        args as Parameters<typeof client.constructQuery>[0],
+      );
+      const result = await client.executeQuery({ query: constructed.query });
+      return {
+        content: [{ type: "text" as const, text: json(result) }],
+        ...(result.status === "failed" && { isError: true }),
+      };
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        content: [{ type: "text" as const, text: msg }],
+        isError: true,
+      };
+    }
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Start the server
+// ---------------------------------------------------------------------------
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Metabase Agent MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/metabase-client.ts

@@ -0,0 +1,332 @@
+const AGENT_API_BASE = "/api/agent/v1";
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export interface MetabaseClientConfig {
+  url: string;
+  apiKey: string;
+  timeoutMs?: number;
+}
+
+export class MetabaseClient {
+  private baseUrl: string;
+  private apiKey: string;
+  private timeoutMs: number;
+
+  constructor(config: MetabaseClientConfig) {
+    this.baseUrl = config.url.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const url = `${this.baseUrl}${AGENT_API_BASE}${path}`;
+    const headers: Record<string, string> = {
+      "X-API-Key": this.apiKey,
+    };
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+    }
+
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `Metabase Agent API error ${res.status} ${res.statusText}: ${text}`,
+      );
+    }
+
+    return res.json() as Promise<T>;
+  }
+
+  async search(params: {
+    term_queries?: string[];
+    semantic_queries?: string[];
+  }): Promise<SearchResponse> {
+    return this.request("POST", "/search", params);
+  }
+
+  async getTable(
+    id: number,
+    opts?: {
+      withFields?: boolean;
+      withFieldValues?: boolean;
+      withRelatedTables?: boolean;
+      withMetrics?: boolean;
+      withMeasures?: boolean;
+      withSegments?: boolean;
+    },
+  ): Promise<Table> {
+    const params = new URLSearchParams();
+    if (opts?.withFields !== undefined)
+      params.set("with-fields", String(opts.withFields));
+    if (opts?.withFieldValues !== undefined)
+      params.set("with-field-values", String(opts.withFieldValues));
+    if (opts?.withRelatedTables !== undefined)
+      params.set("with-related-tables", String(opts.withRelatedTables));
+    if (opts?.withMetrics !== undefined)
+      params.set("with-metrics", String(opts.withMetrics));
+    if (opts?.withMeasures !== undefined)
+      params.set("with-measures", String(opts.withMeasures));
+    if (opts?.withSegments !== undefined)
+      params.set("with-segments", String(opts.withSegments));
+
+    const qs = params.toString();
+    return this.request("GET", `/table/${id}${qs ? `?${qs}` : ""}`);
+  }
+
+  async getFieldValues(
+    entityType: "table" | "metric",
+    entityId: number,
+    fieldId: string,
+  ): Promise<FieldValues> {
+    return this.request(
+      "GET",
+      `/${entityType}/${entityId}/field/${encodeURIComponent(fieldId)}/values`,
+    );
+  }
+
+  async getMetric(
+    id: number,
+    opts?: {
+      withQueryableDimensions?: boolean;
+      withFieldValues?: boolean;
+      withDefaultTemporalBreakout?: boolean;
+      withSegments?: boolean;
+    },
+  ): Promise<Metric> {
+    const params = new URLSearchParams();
+    if (opts?.withQueryableDimensions !== undefined)
+      params.set(
+        "with-queryable-dimensions",
+        String(opts.withQueryableDimensions),
+      );
+    if (opts?.withFieldValues !== undefined)
+      params.set("with-field-values", String(opts.withFieldValues));
+    if (opts?.withDefaultTemporalBreakout !== undefined)
+      params.set(
+        "with-default-temporal-breakout",
+        String(opts.withDefaultTemporalBreakout),
+      );
+    if (opts?.withSegments !== undefined)
+      params.set("with-segments", String(opts.withSegments));
+
+    const qs = params.toString();
+    return this.request("GET", `/metric/${id}${qs ? `?${qs}` : ""}`);
+  }
+
+  async constructQuery(
+    params: ConstructQueryRequest,
+  ): Promise<ConstructQueryResponse> {
+    return this.request("POST", "/construct-query", params);
+  }
+
+  async executeQuery(
+    params: ExecuteQueryRequest,
+  ): Promise<ExecuteQueryResponse> {
+    return this.request("POST", "/execute", params);
+  }
+}
+
+// --- Response types ---
+
+export interface SearchResponse {
+  data: SearchResultItem[];
+  total_count: number;
+}
+
+export interface SearchResultItem {
+  id: number;
+  type: "table" | "metric";
+  name: string;
+  display_name?: string | null;
+  description?: string | null;
+  database_id?: number | null;
+  database_schema?: string | null;
+  verified?: boolean | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+
+export interface Field {
+  field_id: string;
+  name: string;
+  type?: "boolean" | "date" | "datetime" | "time" | "number" | "string" | null;
+  description?: string | null;
+  database_type?: string | null;
+  semantic_type?: string | null;
+  field_values?: unknown[] | null;
+}
+
+export interface Segment {
+  id: number;
+  name: string;
+  description?: string | null;
+  display_name?: string | null;
+}
+
+export interface Measure {
+  id: number;
+  name: string;
+  description?: string | null;
+  display_name?: string | null;
+}
+
+export interface MetricSummary {
+  id: number;
+  type: "metric";
+  name: string;
+  description?: string | null;
+  default_time_dimension_field_id?: string | null;
+}
+
+export interface RelatedTable {
+  id: number;
+  type: "table";
+  name: string;
+  display_name?: string | null;
+  description?: string | null;
+  database_id?: number | null;
+  database_engine?: string | null;
+  database_schema?: string | null;
+  related_by?: string | null;
+  fields?: Field[] | null;
+}
+
+export interface Table {
+  id: number;
+  type: "table" | "metric";
+  name: string;
+  display_name: string;
+  description?: string | null;
+  database_id: number;
+  database_engine: string;
+  database_schema?: string | null;
+  fields: Field[];
+  related_tables?: RelatedTable[] | null;
+  metrics?: MetricSummary[] | null;
+  measures?: Measure[] | null;
+  segments?: Segment[] | null;
+}
+
+export interface Metric {
+  id: number;
+  type: "metric";
+  name: string;
+  description?: string | null;
+  verified?: boolean | null;
+  default_time_dimension_field_id?: string | null;
+  queryable_dimensions?: Field[] | null;
+  segments?: Segment[] | null;
+}
+
+export interface Statistics {
+  distinct_count?: number | null;
+  percent_null?: number | null;
+  min?: number | null;
+  max?: number | null;
+  avg?: number | null;
+  sd?: number | null;
+  q1?: number | null;
+  q3?: number | null;
+  earliest?: string | null;
+  latest?: string | null;
+  average_length?: number | null;
+  percent_email?: number | null;
+  percent_url?: number | null;
+  percent_state?: number | null;
+  percent_json?: number | null;
+}
+
+export interface FieldValues {
+  field_id?: string | null;
+  values?: unknown[] | null;
+  statistics?: Statistics | null;
+}
+
+// --- Query construction types ---
+
+export type Filter =
+  | { segment_id: number }
+  | {
+      field_id: string;
+      operation: string;
+      value?: unknown;
+      values?: unknown[];
+      bucket?: string;
+    };
+
+export interface GroupBy {
+  field_id: string;
+  field_granularity?: string | null;
+}
+
+export interface FieldRef {
+  field_id: string;
+  bucket?: string;
+}
+
+export interface OrderBy {
+  field: FieldRef;
+  direction: "asc" | "desc";
+}
+
+export type Aggregation =
+  | { function: "count"; sort_order?: "asc" | "desc" | null }
+  | {
+      field_id: string;
+      function: "avg" | "count-distinct" | "max" | "min" | "sum";
+      sort_order?: "asc" | "desc" | null;
+    }
+  | { measure_id: number; sort_order?: "asc" | "desc" | null };
+
+export type ConstructQueryRequest =
+  | {
+      table_id: number;
+      filters?: Filter[] | null;
+      fields?: FieldRef[] | null;
+      aggregations?: Aggregation[] | null;
+      group_by?: GroupBy[] | null;
+      order_by?: OrderBy[] | null;
+      limit?: number | null;
+    }
+  | {
+      metric_id: number;
+      filters?: Filter[] | null;
+      group_by?: GroupBy[] | null;
+    };
+
+export interface ConstructQueryResponse {
+  query: string;
+}
+
+export interface ColumnMetadata {
+  name: string;
+  base_type: string;
+  display_name: string;
+  effective_type?: string | null;
+}
+
+export interface ExecuteQueryRequest {
+  query: string;
+}
+
+export interface ExecuteQueryResponse {
+  status: "completed" | "failed";
+  data?: {
+    cols: ColumnMetadata[];
+    rows: unknown[][];
+  };
+  row_count?: number;
+  running_time?: number;
+  error?: string;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/__tests__"]
+}