Metabase MCP Server

Instructions

Implementation Reference

• src/server/handlers/cardHandlers.js:67-98 (handler)

  The main handler function that implements the list_cards tool logic. It fetches cards from the Metabase API using the provided filter and optional modelId, processes them, limits display to 50, and returns formatted text content.

    async listCards(filter = 'all', modelId = null) {
      this.logger.debug('Listing cards', { filter, modelId });
      
      const params = new URLSearchParams({ f: filter });
      if (modelId) {
        params.append('model_id', modelId);
      }
      
      const response = await this.apiClient.makeRequest(`/api/card/?${params}`);
      const cards = Array.isArray(response) ? response : response.data || [];
      
      const cardList = cards.map(card => ({
        id: card.id,
        name: card.name,
        description: card.description,
        databaseId: card.dataset_query?.database,
        queryType: card.dataset_query?.type,
        createdAt: card.created_at,
      }));
  
      return {
        content: [
          {
            type: 'text',
            text: `Found ${cardList.length} cards (filter: ${filter}):
  ${cardList.slice(0, 50).map(card => 
    `- ID: ${card.id} | Name: ${card.name} | DB: ${card.databaseId} | Type: ${card.queryType}`
  ).join('\n')}${cardList.length > 50 ? `\n... and ${cardList.length - 50} more cards` : ''}`,
          },
        ],
      };
    }

• src/server/config/toolDefinitions.js:23-42 (schema)

  The tool definition including name, description, and input schema for validation of list_cards tool parameters.

  {
    name: 'list_cards',
    description: '📋 [SAFE] List Metabase cards/questions with optional filtering. Use this to discover available cards, find cards by type, or see all questions in the system. Can return large results (15k+ cards). Risk: None - read-only, but may be slow with many cards.',
    inputSchema: {
      type: 'object',
      properties: {
        filter: {
          type: 'string',
          description: 'Filter type: all (all cards), mine (my cards), bookmarked, database, table, using_model, using_segment, archived',
          enum: ['all', 'mine', 'bookmarked', 'database', 'table', 'using_model', 'using_segment', 'archived'],
          default: 'all',
        },
        modelId: {
          type: 'integer',
          description: 'Model ID for filtering (only when filter=using_model)',
          minimum: 1,
        },
      },
    },
  },

• src/server/MetabaseMCPServer.js:170-171 (registration)

  The switch case in executeTool method that registers and dispatches the list_cards tool call to the CardHandlers.listCards method.

  case 'list_cards':
    return await this.cardHandlers.listCards(args.filter, args.modelId);