twaddan-metabase-mcp 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# twaddan-metabase-mcp (Metabase MCP for Claude Code)
+
+MCP server that connects Claude Code to your Metabase instance — query databases, explore tables, run SQL, and search saved questions.
+
+## Quick Start
+
+```bash
+npx twaddan-metabase-mcp setup
+```
+
+This will:
+1. Prompt for your Metabase URL and API key
+2. Validate the connection
+3. Register the MCP server with Claude Code
+4. Auto-allow all Metabase tools (no permission prompts)
+
+Then just start Claude Code — all Metabase tools are ready.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_databases` | List all databases connected to Metabase |
+| `list_tables` | List all tables in a specific database |
+| `get_table_metadata` | Get column names, types, and details for a table |
+| `run_sql_query` | Run a native SQL SELECT query against a database |
+| `search_metabase` | Search for saved questions, dashboards, tables, and collections |
+| `run_saved_question` | Execute a saved question/card by its ID |
+
+## Getting a Metabase API Key
+
+1. Log in to your Metabase instance
+2. Go to **Settings** → **Authentication** → **API Keys**
+3. Click **Create API Key**
+4. Copy the generated key
+
+## Manual Setup
+
+If you prefer to configure manually:
+
+```bash
+claude mcp add -s user \
+  -e METABASE_URL=https://metabase.example.com \
+  -e METABASE_API_KEY=your_api_key \
+  metabase -- npx twaddan-metabase-mcp
+```
+
+Then add `"mcp__metabase"` to `~/.claude/settings.json` under `permissions.allow` to skip permission prompts.
+
+## Troubleshooting
+
+**"METABASE_URL environment variable is required"**
+The MCP server was started without environment variables. Re-run `npx twaddan-metabase-mcp setup` or check your Claude Code MCP configuration.
+
+**"Could not connect"**
+- Verify your Metabase URL is accessible from your machine
+- Check that the API key is valid and has not expired
+- Ensure the URL does not have a trailing slash
+
+**Tools not appearing in Claude Code**
+- Run `claude mcp list` to verify the server is registered
+- Restart Claude Code after setup
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+
+// ── Setup CLI: `npx twaddan-metabase-mcp setup` ──
+if (process.argv[2] === 'setup') {
+  const readline = await import('readline');
+  const { execSync } = await import('child_process');
+  const fs = await import('fs');
+  const path = await import('path');
+  const os = await import('os');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+  console.log('\n🔧 Metabase MCP Server — Setup\n');
+
+  const url = (await ask('Metabase URL (e.g. https://metabase.example.com): ')).replace(/\/+$/, '');
+  if (!url) { console.error('URL is required.'); process.exit(1); }
+
+  const apiKey = await ask('Metabase API key: ');
+  if (!apiKey) { console.error('API key is required.'); process.exit(1); }
+
+  rl.close();
+
+  // Validate connection
+  console.log('\nValidating connection...');
+  try {
+    const res = await fetch(`${url}/api/database`, {
+      headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' },
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = await res.json();
+    const count = data.data?.length ?? 0;
+    console.log(`✅ Connected — found ${count} database${count !== 1 ? 's' : ''}\n`);
+  } catch (err) {
+    console.error(`❌ Could not connect to ${url}: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Register MCP server with Claude Code
+  console.log('Registering MCP server with Claude Code...');
+  try {
+    execSync(
+      `claude mcp add -s user -e METABASE_URL=${url} -e METABASE_API_KEY=${apiKey} metabase -- npx twaddan-metabase-mcp`,
+      { stdio: 'inherit' }
+    );
+    console.log('✅ MCP server registered\n');
+  } catch {
+    console.error('❌ Failed to register MCP server. Make sure Claude Code CLI is installed.');
+    process.exit(1);
+  }
+
+  // Auto-allow metabase tools in Claude Code settings
+  console.log('Configuring permissions...');
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  try {
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    }
+    if (!settings.permissions) settings.permissions = {};
+    if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+
+    const rule = 'mcp__metabase';
+    if (!settings.permissions.allow.includes(rule)) {
+      settings.permissions.allow.push(rule);
+      fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+      console.log('✅ Auto-allowed all Metabase tools (mcp__metabase)\n');
+    } else {
+      console.log('✅ Metabase tools already allowed\n');
+    }
+  } catch (err) {
+    console.warn(`⚠️  Could not update settings: ${err.message}`);
+    console.warn('   You may need to manually allow "mcp__metabase" tools in ~/.claude/settings.json\n');
+  }
+
+  console.log('🎉 Setup complete! Start Claude Code and your Metabase tools are ready.\n');
+  process.exit(0);
+}
+
+// ── MCP Server Mode ──
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const METABASE_URL = process.env.METABASE_URL;
+const METABASE_API_KEY = process.env.METABASE_API_KEY;
+
+if (!METABASE_URL) {
+  console.error('METABASE_URL environment variable is required');
+  process.exit(1);
+}
+
+if (!METABASE_API_KEY) {
+  console.error('METABASE_API_KEY environment variable is required');
+  process.exit(1);
+}
+
+const headers = {
+  'x-api-key': METABASE_API_KEY,
+  'Content-Type': 'application/json',
+};
+
+async function metabaseRequest(method, path, body) {
+  const res = await fetch(`${METABASE_URL}${path}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Metabase API error (${res.status}): ${text || res.statusText}`);
+  }
+
+  return res.json();
+}
+
+function formatDataset(data) {
+  const columns = data.data.cols.map(c => c.name);
+  const rows = data.data.rows.map(row => {
+    const obj = {};
+    columns.forEach((col, i) => { obj[col] = row[i]; });
+    return obj;
+  });
+  return { columns, rows, row_count: rows.length };
+}
+
+// Create MCP server
+const server = new McpServer({
+  name: 'metabase',
+  version: '1.0.0',
+});
+
+// Tool: List databases
+server.tool(
+  'list_databases',
+  'List all databases connected to Metabase',
+  {},
+  async () => {
+    const data = await metabaseRequest('GET', '/api/database');
+    const databases = data.data.map(db => ({
+      id: db.id,
+      name: db.name,
+      engine: db.engine,
+    }));
+    return { content: [{ type: 'text', text: JSON.stringify(databases, null, 2) }] };
+  }
+);
+
+// Tool: List tables
+server.tool(
+  'list_tables',
+  'List all tables in a specific database',
+  { database_id: z.number().describe('The Metabase database ID') },
+  async ({ database_id }) => {
+    const data = await metabaseRequest('GET', `/api/database/${database_id}/metadata`);
+    const tables = data.tables.map(t => ({
+      id: t.id,
+      name: t.name,
+      schema: t.schema,
+      description: t.description,
+    }));
+    return { content: [{ type: 'text', text: JSON.stringify(tables, null, 2) }] };
+  }
+);
+
+// Tool: Get table metadata (columns, types)
+server.tool(
+  'get_table_metadata',
+  'Get column names, types, and details for a specific table',
+  { table_id: z.number().describe('The Metabase table ID') },
+  async ({ table_id }) => {
+    const data = await metabaseRequest('GET', `/api/table/${table_id}/query_metadata`);
+    const result = {
+      name: data.name,
+      schema: data.schema,
+      description: data.description,
+      columns: data.fields.map(f => ({
+        name: f.name,
+        type: f.database_type,
+        description: f.description,
+        semantic_type: f.semantic_type,
+      })),
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// Tool: Run native SQL query
+server.tool(
+  'run_sql_query',
+  'Run a native SQL SELECT query against a database via Metabase. Only SELECT/WITH queries allowed.',
+  {
+    database_id: z.number().describe('The Metabase database ID'),
+    sql: z.string().describe('The SQL SELECT query to run'),
+  },
+  async ({ database_id, sql }) => {
+    const trimmed = sql.replace(/--.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '').trim();
+    const upper = trimmed.toUpperCase();
+    if (!upper.startsWith('SELECT') && !upper.startsWith('WITH')) {
+      return { content: [{ type: 'text', text: 'Error: Only SELECT/WITH queries are allowed.' }], isError: true };
+    }
+
+    const data = await metabaseRequest('POST', '/api/dataset', {
+      database: database_id,
+      type: 'native',
+      native: { query: sql },
+    });
+    const result = formatDataset(data);
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// Tool: Search Metabase
+server.tool(
+  'search_metabase',
+  'Search for saved questions, dashboards, tables, and collections in Metabase',
+  { query: z.string().describe('Search query string') },
+  async ({ query }) => {
+    const data = await metabaseRequest('GET', `/api/search?q=${encodeURIComponent(query)}`);
+    const results = data.data.map(item => ({
+      id: item.id,
+      name: item.name,
+      description: item.description,
+      model: item.model,
+      collection: item.collection?.name || null,
+    }));
+    return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+  }
+);
+
+// Tool: Run a saved question
+server.tool(
+  'run_saved_question',
+  'Execute an existing saved question/card in Metabase by its ID',
+  { card_id: z.number().describe('The saved question/card ID') },
+  async ({ card_id }) => {
+    const data = await metabaseRequest('POST', `/api/card/${card_id}/query`);
+    const result = formatDataset(data);
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "twaddan-metabase-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for querying Metabase from Claude Code — databases, tables, SQL, saved questions & search",
+  "type": "module",
+  "bin": {
+    "twaddan-metabase-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "metabase",
+    "claude",
+    "claude-code",
+    "ai",
+    "analytics",
+    "sql",
+    "model-context-protocol"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}