Release commit

Author: akuten1298

README.md

@@ -75,12 +75,44 @@ export METABASE_USERNAME=your_username
 export METABASE_PASSWORD=your_password
 ```
 
+### Optional Arguments
+
+The server supports command-line arguments to customize tool loading:
+
+- **`--essential`** (default): Load only essential tools
+- **`--all`**: Load all 80+ available tools
+- **`--write`**: Load only write/modification tools
+- **`--read`**: Load only read-only tools
+
+```bash
+# Using published package (recommended)
+# Default behavior (essential tools only)
+npx @windsurf-public/mcp-metabase-server
+
+# Load all tools
+npx @windsurf-public/mcp-metabase-server --all
+
+# Load only write tools
+npx @windsurf-public/mcp-metabase-server --write
+
+# Load only read-only tools
+npx @windsurf-public/mcp-metabase-server --read
+
+# Using local development build
+npm run build
+node dist/server.js                    # Default (essential tools)
+node dist/server.js --all             # All tools
+node dist/server.js --write           # Write tools only
+node dist/server.js --read            # Read-only tools only
+```
+
 ## 🔌 Integration Examples
 
 ### Claude Desktop
 
 Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
+**Using published package:**
 ```json
 {
   "mcpServers": {
@@ -96,10 +128,43 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
+**Using local development build:**
+```json
+{
+  "mcpServers": {
+    "metabase": {
+      "command": "node",
+      "args": ["/path/to/metabase-mcp-server/dist/server.js"],
+      "env": {
+        "METABASE_URL": "https://your-metabase-instance.com",
+        "METABASE_API_KEY": "your_metabase_api_key"
+      }
+    }
+  }
+}
+```
+
+**With custom flags:**
+```json
+{
+  "mcpServers": {
+    "metabase-all": {
+      "command": "npx",
+      "args": ["@windsurf-public/mcp-metabase-server", "--all"],
+      "env": {
+        "METABASE_URL": "https://your-metabase-instance.com",
+        "METABASE_API_KEY": "your_metabase_api_key"
+      }
+    }
+  }
+}
+```
+
 ### Windsurf IDE
 
 Add to your Windsurf MCP config (`~/.windsurf/mcp_config.json`):
 
+**Using published package:**
 ```json
 {
   "mcpServers": {
@@ -115,6 +180,46 @@ Add to your Windsurf MCP config (`~/.windsurf/mcp_config.json`):
 }
 ```
 
+**Using local development build:**
+```json
+{
+  "mcpServers": {
+    "metabase": {
+      "command": "node",
+      "args": ["/path/to/metabase-mcp-server/dist/server.js"],
+      "env": {
+        "METABASE_URL": "https://your-metabase-instance.com",
+        "METABASE_API_KEY": "your_metabase_api_key"
+      }
+    }
+  }
+}
+```
+
+**With custom flags:**
+```json
+{
+  "mcpServers": {
+    "metabase-read": {
+      "command": "npx",
+      "args": ["@windsurf-public/mcp-metabase-server", "--read"],
+      "env": {
+        "METABASE_URL": "https://your-metabase-instance.com",
+        "METABASE_API_KEY": "your_metabase_api_key"
+      }
+    },
+    "metabase-write": {
+      "command": "npx",
+      "args": ["@windsurf-public/mcp-metabase-server", "--write"],
+      "env": {
+        "METABASE_URL": "https://your-metabase-instance.com",
+        "METABASE_API_KEY": "your_metabase_api_key"
+      }
+    }
+  }
+}
+```
+
 ## 🛠️ Available Tools
 
 <details>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windsurf-public/mcp-metabase-server",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "A Model Context Protocol server for Metabase integration",
   "author": "Cognition <devin@cognition.ai>",
   "license": "MIT",

src/server.ts

@@ -31,16 +31,25 @@ const server = new FastMCP({
 const originalAddTool = server.addTool.bind(server);
 server.addTool = function(toolConfig: any) {
   const { metadata = {}, ...restConfig } = toolConfig;
-  const { isWrite, isEssential } = metadata;
+  const { isWrite, isEssential, isRead } = metadata;
 
-  // Skip non-essential tools when essential mode is enabled
-  if (filterOptions.essentialOnly && !isEssential) {
-    return;
-  }
-
-  // Skip non-write tools when write mode is disabled
-  if (filterOptions.writeMode && !isWrite) {
-    return;
+  // Apply filtering based on selected mode
+  switch (filterOptions.mode) {
+    case 'essential':
+      // Only load essential tools
+      if (!isEssential) return;
+      break;
+    case 'write':
+      // Only load write tools
+      if (!isWrite) return;
+      break;
+    case 'read':
+      // Only load read-only tools
+      if (!isRead) return;
+      break;
+    case 'all':
+      // Load all tools - no filtering
+      break;
   }
 
   // Register the tool
@@ -58,11 +67,21 @@ addAdditionalTools(server, metabaseClient);
 addMetabaseResources(server, metabaseClient);
 
 // Log filtering status
-if (filterOptions.essentialOnly) {
-  console.error(`INFO: Essential mode enabled`);
-}
-if (filterOptions.writeMode) {
-  console.error(`INFO: Write operations enabled`);
+console.error(`INFO: Tool filtering mode: ${filterOptions.mode} ${filterOptions.mode === 'essential' ? '(default)' : ''}`);
+
+switch (filterOptions.mode) {
+  case 'essential':
+    console.error(`INFO: Only essential tools loaded. Use --all to load all tools.`);
+    break;
+  case 'write':
+    console.error(`INFO: Only write/modification tools loaded.`);
+    break;
+  case 'read':
+    console.error(`INFO: Only read-only tools loaded.`);
+    break;
+  case 'all':
+    console.error(`INFO: All tools loaded.`);
+    break;
 }
 
 // Start the server

src/tools/additional-tools.ts

@@ -16,7 +16,7 @@ export function addAdditionalTools(server: any, metabaseClient: MetabaseClient)
   server.addTool({
     name: "get_collection_items",
     description: "Retrieve all items (cards, dashboards) within a Metabase collection - use this to explore collection contents, organize analytical assets, or understand content structure",
-    metadata: { isEssential: true },
+    metadata: { isEssential: true, isRead: true },
     parameters: z.object({
       collection_id: z.number().describe("Collection ID"),
     }),
@@ -97,7 +97,7 @@ export function addAdditionalTools(server: any, metabaseClient: MetabaseClient)
   server.addTool({
     name: "search_content",
     description: "Search across all Metabase content including cards, dashboards, collections, and models - use this to find specific content, discover assets, or explore analytical resources",
-    metadata: { isEssential: true },
+    metadata: { isEssential: true, isRead: true },
     parameters: z
       .object({
         q: z.string().min(1).describe("Search query"),
@@ -137,7 +137,7 @@ export function addAdditionalTools(server: any, metabaseClient: MetabaseClient)
   server.addTool({
     name: "list_collections",
     description: "Retrieve all Metabase collections for organizing analytical content - use this to understand content structure, find collections, or explore organizational hierarchy",
-    metadata: { isEssential: true },
+    metadata: { isEssential: true, isRead: true },
     parameters: z.object({
       archived: z.boolean().optional().default(false).describe("Include archived collections"),
     }),
@@ -264,7 +264,7 @@ export function addAdditionalTools(server: any, metabaseClient: MetabaseClient)
   server.addTool({
     name: "list_users",
     description: "Retrieve all Metabase users with their roles and permissions - use this to understand user access, manage permissions, or audit accounts",
-    metadata: { isEssential: true },
+    metadata: { isEssential: true, isRead: true },
     parameters: z.object({
       include_deactivated: z.boolean().optional().default(false).describe("Include deactivated users"),
     }),

src/tools/card-tools.ts

@@ -17,7 +17,7 @@ export function addCardTools(server: any, metabaseClient: MetabaseClient) {
   server.addTool({
     name: "list_cards",
     description: "Retrieve all Metabase cards with optional filtering by source type (e.g., 'models') or model relationships - use this to discover available cards, find specific cards by type, or get an overview of all analytical content",
-    metadata: { isEssential: true },
+    metadata: { isEssential: true, isRead: true },
     parameters: z.object({
       f: z.string().optional().describe("Filter by source (e.g., 'models')"),
       model_id: z.number().optional().describe("Filter by model_id"),
@@ -47,6 +47,7 @@ export function addCardTools(server: any, metabaseClient: MetabaseClient) {
   server.addTool({
     name: "get_card",
     description: "Get complete metadata and configuration for a specific Metabase card including query definition, visualization settings, collection location, and permissions - use this when you need to examine or understand how a particular card is built",
+    metadata: { isEssential: true, isRead: true },
     parameters: z.object({
       card_id: z.number().describe("Card ID"),
     }),
@@ -258,6 +259,7 @@ export function addCardTools(server: any, metabaseClient: MetabaseClient) {
   server.addTool({
     name: "export_card_result",
     description: "Execute a Metabase card and export the results in a specific format (CSV, Excel, JSON, etc.) - use this to download data for external analysis, create reports for stakeholders, or integrate query results with other systems",
+    metadata: { isEssential: true },
     parameters: z.object({
       card_id: z.number().describe("Card ID"),
       export_format: z.string().describe("Export format (e.g., csv, xlsx, json)"),
@@ -329,7 +331,7 @@ export function addCardTools(server: any, metabaseClient: MetabaseClient) {
   server.addTool({
     name: "get_card_dashboards",
     description: "Find all dashboards that include a specific Metabase card - use this to understand where a card is being used, track dependencies before making changes, or find related analytical content",
-    metadata: { isEssential: true },
+    metadata: { isEssential: true, isRead: true },
     parameters: z.object({
       card_id: z.number().describe("Card ID"),
     }),
@@ -359,6 +361,7 @@ export function addCardTools(server: any, metabaseClient: MetabaseClient) {
   server.addTool({
     name: "list_embeddable_cards",
     description: "Retrieve all Metabase cards configured for embedding in external applications (requires admin privileges) - use this to audit embedded content, manage external integrations, or review public-facing analytics",
+    metadata: { isRead: true },
     execute: async () => {
       try {
         const result = await metabaseClient.getEmbeddableCards();
@@ -445,6 +448,7 @@ export function addCardTools(server: any, metabaseClient: MetabaseClient) {
   server.addTool({
     name: "list_public_cards",
     description: "Retrieve all Metabase cards that have public URLs enabled (requires admin privileges) - use this to audit publicly accessible content, review security settings, or manage external data sharing",
+    metadata: { isRead: true },
     execute: async () => {
       try {
         const result = await metabaseClient.getPublicCards();
@@ -587,6 +591,7 @@ export function addCardTools(server: any, metabaseClient: MetabaseClient) {
   server.addTool({
     name: "get_card_param_values",
     description: "Retrieve all available values for a specific parameter in a Metabase card - use this to populate dropdown filters, validate parameter inputs, or understand what data options are available for interactive cards",
+    metadata: { isRead: true },
     parameters: z.object({
       card_id: z.number().describe("Card ID"),
       param_key: z.string().describe("Parameter key"),
@@ -623,6 +628,7 @@ export function addCardTools(server: any, metabaseClient: MetabaseClient) {
   server.addTool({
     name: "search_card_param_values",
     description: "Search and filter available parameter values for a Metabase card using a text query - use this to find specific parameter options in large datasets, help users locate filter values, or implement autocomplete functionality",
+    metadata: { isRead: true },
     parameters: z.object({
       card_id: z.number().describe("Card ID"),
       param_key: z.string().describe("Parameter key"),