# MotherDuck Documentation - Microsoft Power BI > Power BI is an interactive data visualization product developed by Microsoft. You can connect Power BI to MotherDuck through the built-in PostgreSQL database connector using MotherDuck's Postgres endpoint. Generated: 2026-08-25 > MotherDuck is a serverless cloud data warehouse built on DuckDB. It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics. ## Key capabilities - **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses) - **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session - **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language - **Data Sharing**: Share databases and query results with team members and external users - **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI - **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more - **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation ## When to use MotherDuck Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP. ## Agent guidance If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation. For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows. To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question. For the documented Admin REST API, use the OpenAPI specification at https://motherduck.com/docs/openapi.json. ## Account setup for agents If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request. `POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`. Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership. Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup. ## Included documentation Source: https://motherduck.com/docs/integrations/bi-tools/powerbi/powerbi-desktop # Power BI Desktop with MotherDuck > Connect Power BI Desktop to MotherDuck using the Postgres endpoint for dashboards and reports. :::info[Preview] The Postgres endpoint is in [preview](/about-motherduck/feature-stages/). Features and behavior may change. ::: :::warning[Looking for the custom connector?] The DuckDB custom connector is a legacy approach. If you still need it, see the [legacy custom connector guide](./powerbi-custom-connector.md). ::: ## Before you start You'll need: - [Power BI Desktop](https://www.microsoft.com/en-us/power-platform/products/power-bi/desktop) installed on Windows - A [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) - Your Postgres host, which you can find at [MotherDuck Postgres settings](https://app.motherduck.com/settings/postgres) (for example, `pg.us-east-1-aws.motherduck.com`) ## Connect to MotherDuck 1. In Power BI Desktop, click **Get data**. ![Power BI Get Data dialog showing PostgreSQL database connector](/img/integrations/powerbi-pg-get-data.png) 2. Search for **PostgreSQL database** in the connector list and select it. 3. Fill in the connection details: - **Server**: Your Postgres host (for example, `pg.us-east-1-aws.motherduck.com`). You can find this at [MotherDuck Postgres settings](https://app.motherduck.com/settings/postgres). - **Database**: Your database or share name in MotherDuck (for example, `sample_data`). 4. Select a data connectivity mode: - **DirectQuery**: Queries run against MotherDuck in real time. Best for dashboards that need up-to-date data. - **Import**: Loads a snapshot of the data into Power BI's in-memory model. Best when you want fast local interactions and can refresh on a schedule. ![Power BI PostgreSQL connection dialog with server and database fields](/img/integrations/powerbi-pg-connection.png) 5. Click **OK**. 6. When prompted for credentials, select **Database** on the left and enter: - **User name**: `postgres` - **Password**: Your [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) ![Power BI credentials dialog with user name and password fields](/img/integrations/powerbi-pg-credentials.png) 7. Click **Connect**. In the Navigator, select the tables you want to use and click **Load**. ![Power BI Navigator showing tables from MotherDuck](/img/integrations/powerbi-pg-navigator.png) 8. You can build visualizations with your MotherDuck data. ![Power BI dashboard with visualizations from MotherDuck data](/img/integrations/powerbi-pg-query-result.png) ## Connection parameters | Parameter | Value | |-----------|-------| | **Server** | `pg.-aws.motherduck.com` (find yours at [Postgres settings](https://app.motherduck.com/settings/postgres) or with [`md_user_info()`](/sql-reference/motherduck-sql-reference/md-user-info)) | | **Database** | Your database name or share name | | **User name** | `postgres` | | **Password** | Your [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) | ## Additional information - [Postgres endpoint reference](/sql-reference/postgres-endpoint) for connection parameters, SSL options, and limitations - [Connect through the Postgres endpoint](/key-tasks/authenticating-and-connecting-to-motherduck/postgres-endpoint) for a general how-to guide - [Power BI documentation](https://learn.microsoft.com/en-us/power-bi/connect-data/) --- Source: https://motherduck.com/docs/integrations/bi-tools/powerbi/powerbi-service # Power BI Service with MotherDuck > Publish Power BI reports to the cloud using the On-Premises Data Gateway and MotherDuck's Postgres endpoint. :::info[Preview] The Postgres endpoint is in [preview](/about-motherduck/feature-stages/). Features and behavior may change. ::: Power BI Service is the cloud-based version of Power BI that lets you publish, share, and schedule refreshes for reports and dashboards. To connect Power BI Service to MotherDuck, you need a Microsoft On-Premises Data Gateway that bridges the cloud service to MotherDuck's Postgres endpoint. Both **Import** and **DirectQuery** modes work through the gateway. ## Before you start You'll need: - A published `.pbix` report connected to MotherDuck through the [Power BI Desktop setup](./powerbi-desktop.mdx) - A [Power BI Pro or Premium Per User](https://www.microsoft.com/en-us/power-platform/products/power-bi/pricing) license (required for sharing reports and using the standard gateway) - A [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) - A Windows machine to host the gateway (see [Microsoft's gateway requirements](https://learn.microsoft.com/en-us/data-integration/gateway/service-gateway-install#requirements)) ## Install the gateway 1. Download the standard gateway installer from [Microsoft's gateway download page](https://aka.ms/on-premises-data-gateway-installer). Download the **standard (enterprise) gateway**, not the personal mode gateway. 2. Run the installer and accept the default installation path. 3. After installation, the configuration wizard opens. Sign in with your **Microsoft work or school account** (the one associated with your Power BI tenant). 4. Select **Register a new gateway on this computer**. 5. Enter a gateway name (for example, `MD-PG-Gateway`) and a recovery key. Store the recovery key securely. 6. Click **Configure** and wait for registration to complete. **Verify:** The configuration wizard shows "The gateway is online and ready to be used." The Windows service `On-premises data gateway service` should be running in `services.msc`. ![On-premises data gateway configuration wizard showing the gateway is online and ready](/img/integrations/powerbi-service-gateway-ready.png) ## Add a MotherDuck data source 1. In [Power BI Service](https://app.powerbi.com), click the **Settings gear** and select **Manage connections and gateways**. 2. Verify your gateway shows **Online**. 3. Click **+ New** and select **On-premises**. 4. Fill in the connection details: | Field | Value | |-------|-------| | **Gateway cluster name** | Select your gateway | | **Connection name** | A descriptive name (for example, `MotherDuck-PG-sample_data`) | | **Data Source Type** | **PostgreSQL** | | **Server** | Your Postgres host (for example, `pg.us-east-1-aws.motherduck.com`) | | **Database** | Your MotherDuck database name | | **Authentication method** | **Basic** | | **Username** | `postgres` | | **Password** | Your [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) | | **Encrypted Connection** | Checked | | **Privacy Level** | Organizational | ![Power BI Service new connection dialog with gateway, server, and database fields](/img/integrations/powerbi-service-new-connection.png) ![Power BI Service connection dialog showing authentication, encryption, and privacy settings](/img/integrations/powerbi-service-connection-auth.png) 5. Click **Create**. :::warning The **Server** and **Database** values must match your `.pbix` file character-for-character. If they differ, the published dataset won't find the gateway data source. ::: ## Publish and connect a report 1. In Power BI Desktop, publish your report: **File > Publish > Publish to Power BI** and select a workspace. 2. In Power BI Service, go to the workspace and find the semantic model (dataset). 3. Open **Settings** for the semantic model and expand **Gateway and cloud connections**. 4. Map the connection to your gateway data source. ![Power BI Service gateway and cloud connections settings showing the gateway mapped to a MotherDuck data source](/img/integrations/powerbi-service-gateway-mapping.png) 5. Under **Data source credentials**, click **Edit credentials** and enter: - Authentication method: **Basic** - User name: `postgres` - Password: Your MotherDuck access token - Encrypted connection: Checked 6. Click **Sign in**. ## Set up scheduled refresh For reports using **Import** mode, you can configure automatic data refreshes. 1. In the semantic model settings, expand **Refresh**. 2. Toggle **Keep your data up to date** to **On**. 3. Set your refresh frequency and time zone. 4. Click **Apply**. To verify, trigger a manual refresh: open the semantic model's three-dot menu and select **Refresh now**. All steps should complete with green check marks. ![Power BI Service refreshing data dialog showing all steps completed successfully](/img/integrations/powerbi-service-refresh-complete.png) ## DirectQuery through the gateway For reports using **DirectQuery** mode, queries run against MotherDuck in real time through the gateway. No scheduled refresh is needed since data is always live. After publishing and mapping the gateway data source (steps above), DirectQuery reports work automatically in Power BI Service. ![Power BI Service showing a report with visualizations from MotherDuck data](/img/integrations/powerbi-service-report.png) ## Connection parameters | Parameter | Value | |-----------|-------| | **Server** | `pg.-aws.motherduck.com` (find yours at [Postgres settings](https://app.motherduck.com/settings/postgres) or with [`md_user_info()`](/sql-reference/motherduck-sql-reference/md-user-info)) | | **Database** | Your database name | | **Username** | `postgres` | | **Password** | Your [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) | | **Encrypted Connection** | Checked | ## Troubleshooting ### Gateway shows offline Check the gateway machine is on, connected to the network, and the `On-premises data gateway service` Windows service is running. Restart the service if needed. ### Firewall blocking port 5432 If `Test-NetConnection -ComputerName pg.us-east-1-aws.motherduck.com -Port 5432` returns `TcpTestSucceeded: False`, add an outbound firewall rule allowing TCP 5432 to the MotherDuck Postgres host. ### SSL/TLS handshake failure MotherDuck uses certificates from a publicly trusted CA, so the gateway should trust them by default. If you see "The remote certificate is invalid," run Windows Update to refresh the root CA store, or manually import the ISRG Root X1 certificate into the machine-level Trusted Root Certification Authorities store. After importing, restart the gateway service. ### Credential errors - The username must be `postgres`. - The password is your **MotherDuck access token** (starting with `md_`), not your web UI password. - Check for trailing whitespace in the token. ### Published dataset doesn't see the gateway The **Server** and **Database** values in the gateway data source must match the `.pbix` file exactly, including case. Recreate the data source with the correct values if they differ. ## Additional information - [Postgres endpoint reference](/sql-reference/postgres-endpoint) for connection parameters, SSL options, and limitations - [Connect through the Postgres endpoint](/key-tasks/authenticating-and-connecting-to-motherduck/postgres-endpoint) for a general how-to guide - [Microsoft gateway documentation](https://learn.microsoft.com/en-us/power-bi/connect-data/service-gateway-onprem) - [Power BI Service documentation](https://learn.microsoft.com/en-us/power-bi/fundamentals/power-bi-service-overview) --- Source: https://motherduck.com/docs/integrations/bi-tools/powerbi/powerbi-custom-connector # Power BI custom connector (legacy) > Connect Power BI to MotherDuck using the DuckDB ODBC driver and Power Query custom connector. :::warning[Legacy] The custom connector is a legacy approach. Use the [Postgres endpoint setup](./powerbi-desktop.mdx) instead for a simpler connection that doesn't require installing drivers or custom extensions. ::: The open-source [DuckDB Power Query Connector](https://github.com/motherduckdb/duckdb-power-query-connector/) lets you connect Power BI to DuckDB and MotherDuck using the DuckDB ODBC driver. ## Installing 1. Download the latest MotherDuck-supported DuckDB ODBC driver that matches your Power BI architecture: - [Windows AMD64](https://github.com/duckdb/duckdb-odbc/releases/download/v1.5.5.0/duckdb_odbc-windows-amd64.zip) - [Windows ARM64](https://github.com/duckdb/duckdb-odbc/releases/download/v1.5.5.0/duckdb_odbc-windows-arm64.zip) See [the releases page](https://github.com/duckdb/duckdb-odbc/releases) for other versions and architectures. For more information about the Windows ODBC Driver, see the [DuckDB Docs page on DuckDB ODBC API on Windows](https://duckdb.org/docs/stable/clients/odbc/windows). 2. Extract the `.zip` archive. Run `odbc_install.exe`. If Windows displays a security warning, click "More information" then "Run Anyway". 3. Optionally, verify the installation in the Registry Editor: - Open Registry Editor by running `regedit` - Navigate to `HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\DuckDB` - Confirm the Driver field shows your installed version - If incorrect, delete the `DuckDB` registry key and reinstall 4. Configure Power BI security settings to allow loading of custom extensions: - Go to File -> Options and settings -> Options -> Security -> Data Extensions - Enable "Allow any extensions to load without validation or warning" - ![Dialog window showing Power BI Options to Security to Data Extensions](/img/integrations/PowerBI-data-extensions.png) 5. Download the latest version of the DuckDB Power Query extension: - [duckdb-power-query-connector.mez](https://github.com/MotherDuck-Open-Source/duckdb-power-query-connector/releases/latest/download/duckdb-power-query-connector.mez) 6. Create the Custom Connectors directory if it does not yet exist: - Navigate to `[Documents]\Power BI Desktop\Custom Connectors` - Create this folder, if it doesn't exist - Note: If this location does not work you may need to place this in your OneDrive Documents folder instead 7. Copy the `duckdb-power-query-connector.mez` file into the Custom Connectors folder 8. Restart Power BI Desktop ## How to use with Power BI 1. In Power BI Desktop, click "Get Data" -> "More..." ![Power BI Get Data dialog](/img/integrations/PowerBI-get-data.png) 2. Search for "DuckDB" in the connector search box and select the DuckDB connector ![Power BI connector search showing the DuckDB connector](/img/integrations/PowerBI-Select-source-duckdb.png) 3. For MotherDuck connections, you'll need to provide: - Database Location: Use the `md:` prefix followed by your database name (for example, `md:my_database`). This can also be a local file path (for example, `~\my_database.db`) or an in-memory database (`:memory:`). - MotherDuck Token: Get your token from [MotherDuck's token page](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#creating-an-access-token). *For local DuckDB connections:* Enter "localtoken" to enable the connection. ![Power BI DuckDB connection dialog](/img/integrations/PowerBI-duckdb-database.png) - Read Only (Optional): Set to `true` if you only need read access. - Saas_mode (Optional): Set to `true` to disable [DuckDB extensions](../../../concepts/duckdb-extensions.md). - Attach_mode (Optional): Set to `single` to scope the connection to one database (recommended for BI-tool catalog browsers, which can be confused by multiple attached databases). Leave blank to use the default workspace mode and see all databases in your workspace. See [Attach modes](/key-tasks/authenticating-and-connecting-to-motherduck/attach-modes/). 4. Click "OK". 5. Click "Connect". ![Power BI connection dialog for MotherDuck through the DuckDB connector](/img/integrations/PowerBI-DuckDB-connect.png) 6. Select the table(s) you want to import. Click "Load". ![Power BI Navigator dialog previewing and selecting tables](/img/integrations/PowerBI-data-selection.png) 7. You can query your data and create visualizations. ![Power BI report built from MotherDuck data](/img/integrations/PowerBI-example-graph.png) 8. After connecting, you can: - Browse and select tables from your MotherDuck or DuckDB database - Use "Transform Data" to modify your queries before loading - Write custom SQL queries using the "Advanced Editor" - Import multiple tables in one go 9. Power BI maintains the connection to your MotherDuck or DuckDB database, letting you: - Refresh data automatically or on-demand - Create relationships between tables - Build visualizations and dashboards - Share reports with other users (requires proper gateway setup) ## Use custom data connectors with an on-premises data gateway You can use custom data connectors with an on-premises data gateway to connect to data sources that are not supported by default. To do this, you need to install the on-premises data gateway and configure it to use the custom data connector. For more information, see [Use custom data connectors with an on-premises data gateway in Power BI](https://learn.microsoft.com/en-us/power-bi/connect-data/service-gateway-custom-connectors). There are some limitations with using a custom connector with an on-premises data gateway: - The folder you create must be accessible to the background gateway service. Folders under user Windows folders or system folders typically aren't accessible. The on-premises data gateway app shows a message if the folder isn't accessible. This limitation doesn't apply to the on-premises data gateway (personal mode). - If your custom connector is on a network drive, include the fully qualified path in the on-premises data gateway app. - You can only use one custom connector data source when working in DirectQuery mode. Multiple custom connector data sources don't work with DirectQuery. ## Additional information - [Power BI documentation](https://learn.microsoft.com/en-us/power-bi/connect-data/) - [DuckDB Power Query Connector](https://github.com/motherduckdb/duckdb-power-query-connector/) - [ODBC](/getting-started/interfaces/client-apis/other/odbc/#authenticating-with-an-access-token), for connecting through a DuckDB DSN instead of the connector and authenticating that DSN with an access token ## Troubleshooting ### Missing VCRUNTIME140.dll If you receive an error about missing `VCRUNTIME140.dll`, you need to install the Microsoft Visual C++ Redistributable. You can download it from [Microsoft's download page](https://www.microsoft.com/en-us/download/details.aspx?id=52685). ### Visual C++ and ODBC issues :::note These steps are particularly relevant for Windows Server environments, especially for Windows Server 2019, but may also help resolve issues on other Windows versions. ::: If you encounter issues with ODBC connectivity or receive errors related to Visual C++ libraries, try these troubleshooting steps: 1. Reinstall the Microsoft Visual C++ Redistributable: - Download the latest version from [Microsoft's official website](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170) for your architecture - Run the installer with administrator privileges - Restart your computer after installation - Try connecting to MotherDuck again 2. If you're still experiencing issues, you can use the ODBC Test tool to diagnose the connection: - Open the ODBC Test tool (typically available in Windows SDK) - Look for a dropdown menu labeled "hstmt 1: ..." - Select this option to run test queries - If queries work in the ODBC Test tool but not in Power BI, this indicates a Power BI-specific configuration issue If you continue to experience problems after trying these steps: - Verify that your MotherDuck token is valid and hasn't expired - Check that your network allows connections to MotherDuck's services - Confirm you have the latest version of the DuckDB Power Query Connector installed If you're still experiencing issues, reach out to us at [support@motherduck.com](mailto:support@motherduck.com) and we'll be happy to help you troubleshoot the issue. --- Source: https://motherduck.com/docs/integrations/bi-tools/powerbi/index # Microsoft Power BI > Power BI is an interactive data visualization product developed by Microsoft. You can connect Power BI to MotherDuck through the built-in PostgreSQL database connector using MotherDuck's Postgres endpoint. ## Included pages - [Power BI Desktop with MotherDuck](https://motherduck.com/docs/integrations/bi-tools/powerbi/powerbi-desktop): Connect Power BI Desktop to MotherDuck using the Postgres endpoint for dashboards and reports. - [Power BI Service with MotherDuck](https://motherduck.com/docs/integrations/bi-tools/powerbi/powerbi-service): Publish Power BI reports to the cloud using the On-Premises Data Gateway and MotherDuck's Postgres endpoint. - [Power BI custom connector (legacy)](https://motherduck.com/docs/integrations/bi-tools/powerbi/powerbi-custom-connector): Connect Power BI to MotherDuck using the DuckDB ODBC driver and Power Query custom connector. --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fintegrations%2Fbi-tools%2Fpowerbi%2F&page_title=MotherDuck%20Documentation%20-%20Microsoft%20Power%20BI&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.