DBeaver MCP Server

Instructions

Implementation Reference

• src/index.ts:221-243 (schema)

  Tool definition and input schema for 'execute_query', specifying required connectionId and query parameters with optional maxRows.

  {
    name: 'execute_query',
    description: 'Execute a SQL query on a specific DBeaver connection (read-only queries)',
    inputSchema: {
      type: 'object',
      properties: {
        connectionId: {
          type: 'string',
          description: 'The ID or name of the DBeaver connection to use',
        },
        query: {
          type: 'string',
          description: 'The SQL query to execute (SELECT statements only)',
        },
        maxRows: {
          type: 'number',
          description: 'Maximum number of rows to return (default: 1000)',
          default: 1000
        }
      },
      required: ['connectionId', 'query'],
    },
  },

• src/index.ts:487-492 (registration)

  Registration and dispatching logic in the CallToolRequest handler that routes 'execute_query' calls to the handleExecuteQuery method.

  case 'execute_query':
    return await this.handleExecuteQuery(args as { 
      connectionId: string; 
      query: string; 
      maxRows?: number 
    });

• src/index.ts:624-669 (handler)

  Primary handler for execute_query: sanitizes inputs, validates query, ensures connection exists, optionally adds LIMIT, executes query via DBeaverClient, and formats response.

  private async handleExecuteQuery(args: { 
    connectionId: string; 
    query: string; 
    maxRows?: number 
  }) {
    const connectionId = sanitizeConnectionId(args.connectionId);
    const query = args.query.trim();
    const maxRows = args.maxRows || 1000;
    
    // Validate query
    const validationError = validateQuery(query);
    if (validationError) {
      throw new McpError(ErrorCode.InvalidParams, validationError);
    }
    
    const connection = await this.configParser.getConnection(connectionId);
    if (!connection) {
      throw new McpError(ErrorCode.InvalidParams, `Connection not found: ${connectionId}`);
    }
    
    // Add LIMIT clause if not present and it's a SELECT query
    let finalQuery = query;
    if (query.toLowerCase().trimStart().startsWith('select') && 
        !query.toLowerCase().includes('limit')) {
      finalQuery = `${query} LIMIT ${maxRows}`;
    }
    
    const result = await this.dbeaverClient.executeQuery(connection, finalQuery);
    
    const response = {
      query: finalQuery,
      connection: connection.name,
      executionTime: result.executionTime,
      rowCount: result.rowCount,
      columns: result.columns,
      rows: result.rows,
      truncated: result.rows.length >= maxRows
    };
    
    return {
      content: [{
        type: 'text' as const,
        text: JSON.stringify(response, null, 2),
      }],
    };
  }

• src/dbeaver-client.ts:28-39 (helper)

  Supporting method executeQuery in DBeaverClient that handles actual query execution using native tools based on database driver (SQLite/PostgreSQL), called by the main handler.

  async executeQuery(connection: DBeaverConnection, query: string): Promise<QueryResult> {
    const startTime = Date.now();
    
    try {
      // Use native database tools instead of DBeaver command line
      const result = await this.executeWithNativeTool(connection, query);
      result.executionTime = Date.now() - startTime;
      return result;
    } catch (error) {
      throw new Error(`Query execution failed: ${error}`);
    }
  }