Docs  \  AI  \  AI tools  \ 

Set up Qwen Code for agentic development with Power BI Desktop

This article describes how to configure Qwen Code so that an AI agent can read and modify a Power BI semantic model open in Power BI Desktop, and the report of a Power BI project.

The only requirement we assume is Power BI Desktop, already installed. Everything else is part of this setup.

Sample model used in all the steps: ContosoDemo10k.zip. Please, download it before you start.

At the end you have an agent in the terminal that reads and writes the semantic model, and that also creates and validates report pages.

One warning before you start, because it changes the cost of this setup: the free tier that used the sign-in with a Qwen account was discontinued on 15 April 2026. Qwen Code today needs an API key of a paid service, or of a compatible provider. Step 5 covers the choice.

Requirements

  • Power BI Desktop, installed.
  • Node.js 22 or later. Qwen Code requires it, and the Power BI Modeling MCP server is started with npx, which is part of Node.js. A new machine does not have it, so step 1 installs it.
  • An API key of a provider that Qwen Code supports, including any endpoint compatible with the OpenAI protocol. There is no free tier with a personal account. The key, the address of the service, and the names of the models all depend on the subscription you buy, so read the three in the console of your provider before you start, as in step 5.
  • Git for Windows. The repository of the skills is downloaded with git, and Windows does not include it. Step 11 installs it.
  • Write permission on any semantic model you modify. The MCP server follows the same rules as the Power BI external tools.

MCP stands for Model Context Protocol. The Power BI Modeling MCP server runs on your machine and connects to Power BI Desktop like an external tool. Qwen Code is the client that hosts the agent, and it starts the server as a local process.

Back up your model before an agent writes to it. With the sample model, extract the archive again if something goes wrong.

Step 1: install Node.js

A new installation of Windows does not have it. npm and npx are part of Node.js, and the Power BI Modeling MCP server is started with npx.

Open the command prompt

Several steps of this article ask you to type a command. Windows has two programs that run the commands, and they are not interchangeable:

  • The command prompt. Press Windows+R, type cmd, and press Enter. The window shows a folder path followed by >.
  • PowerShell. Press Windows+R, type powershell, and press Enter. The line starts with PS.

Every command of this article says which of the two to use. To open a window already positioned in a folder, open that folder in File Explorer, type cmd in the address bar, and press Enter. When an installation asks for administrator rights, find Command Prompt in the Start menu, right-click it, and choose Run as administrator.

Install Node.js

Choose one of the two methods. LTS stands for Long Term Support.

Option 1: the installer. Download it from nodejs.org/en/download and run it.

Option 2: WinGet. In the command prompt:

winget install --id OpenJS.NodeJS.LTS --source winget

Both methods write in the folders of the machine, so they ask for administrator rights. If you do not have them, use one of the options at the end of this step.

Close the command prompt and open it again, so that it reads the updated path. Then verify the installation, in the command prompt:

node --version

The command returns the version you installed. The LTS installer provides 22 or later.

Install Node.js without administrator rights

These are options, not a replacement of the installer. Use one of them when the machine is managed and you do not have administrator rights. Each one writes in your user profile, and each one provides npm and npx.

Option 1: the standalone binary. The download page offers a standalone archive besides the installer. Extract it in a folder of your user profile, for example %LOCALAPPDATA%\nodejs, and add that folder to the Path variable of the user, in Settings > System > About > Advanced system settings > Environment variables. Nothing else is installed.

Option 2: fnm, the Fast Node Manager. It installs and switches the versions of Node.js in your user profile. Install fnm with WinGet, in the command prompt:

winget install Schniz.fnm

Add this line to your PowerShell profile, so that every session finds Node.js. The command notepad $PROFILE, typed in PowerShell, opens that file:

fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression

Open a new PowerShell window, install the LTS version, and read the version number it installed:

fnm install --lts

fnm list

Then set that version as the default, replacing <version> with the number of the LTS entry of the list:

fnm default <version>

Option 3: Scoop. It is a package manager that installs in %USERPROFILE%\scoop. Install it in PowerShell, in a window that is not elevated:

irm get.scoop.sh | iex

Then install Node.js, in the same PowerShell window:

scoop install nodejs-lts

With any of the three options, close the window, open a command prompt, and verify with node --version and npm --version.

Step 2: install Qwen Code

Choose one of the two methods.

Option 1: the installer of the project. In PowerShell:

irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

Option 2: npm. In the command prompt:

npm install -g @qwen-code/qwen-code@latest

There is no Microsoft Store version and no WinGet package of Qwen Code. The Store contains the Qwen chat application, which is a different product and does not run agents on your machine.

Qwen Code runs natively on Windows. The Windows Subsystem for Linux is not required.

Verify the installation, in the command prompt:

qwen --version

Step 3: open the sample model

  1. Download ContosoDemo10k.zip.
  2. Extract the archive in a local folder, for example C:\Demo. Please, do not open the file directly from the compressed folder.
  3. Open ContosoDemo10k.pbix in Power BI Desktop and leave Power BI Desktop open.

The title bar shows ContosoDemo10k. You use that name in step 6.

Step 4: register the Power BI Modeling MCP server

There is no extension to install. The server is an npm package, and Qwen Code starts it on demand.

Run this command in the command prompt:

qwen mcp add --scope user powerbi-modeling-mcp npx -- -y @microsoft/powerbi-modeling-mcp@latest --start --readonly

The position of the double dash matters, and it is the one place where this command is easy to get wrong. The syntax is qwen mcp add [options] <name> <commandOrUrl> [args...], so the double dash goes after npx, which is the command, and not before it. Written before npx, it leaves the client with one argument instead of two, and the command fails with Not enough non-option arguments: got 1, need at least 2. Written after npx, it stops the client from reading -y, --start, and --readonly as its own options, and passes them to the server.

The --readonly argument blocks every write operation. We suggest it for the first session, so that a wrong prompt cannot modify anything. Step 8 replaces it.

The --scope user argument writes the entry in %USERPROFILE%\.qwen\settings.json, and this is the scope we suggest. A server registered in the project, in .qwen\settings.json, waits for an approval with qwen mcp approve before it connects, and asks for it again after every change of the entry.

You can edit the file directly instead of running the command:

{
  "mcpServers": {
    "powerbi-modeling-mcp": {
      "command": "npx",
      "args": ["-y", "@microsoft/powerbi-modeling-mcp@latest", "--start", "--readonly"],
      "timeout": 600000,
      "trust": false
    }
  }
}

The timeout value is in milliseconds. Verify the registration, in the command prompt:

qwen mcp list

Step 5: start the agent and sign in

  1. Open a command prompt in the folder that contains the sample, for example C:\Demo.

  2. Start the client:

    qwen

  3. Configure the provider and the key; if the request does not appear, use the following command:

    /auth

    The menu offers the providers of Alibaba Cloud, the third-party providers, and a custom provider for any endpoint compatible with the OpenAI protocol.

    Read the values in the console of your subscription. The entries of the menu named after a commercial plan assume that precise plan, and each one carries a fixed address of the service. A key issued for a different plan, or in a different region, is refused by that address with an error of authentication, and no file of configuration corrects it, because the entry of the menu wins over the environment and over the files. When the name of your subscription does not appear in the menu, or when you are not certain of the correspondence, choose the provider compatible with the OpenAI protocol and write the three values yourself:

    • the API key;
    • the base URL, exactly as the console publishes it, which changes with the plan and with the region;
    • the name of the model, which is one of those included in your subscription.

  4. Verify the configuration:

    /doctor

  5. Verify the authentication, before anything else:

    say hello

    An answer means that the key, the address, and the model agree with each other. An error means that they do not, and no step of this article can work until they do.

The approval mode is auto by default, and the values are plan, default, auto-edit, auto, and yolo. Keep default for this setup, so that every write asks for a confirmation. Start the client in the command prompt with this argument:

qwen --approval-mode default

Step 6: connect to Power BI Desktop

Send this prompt:

Connect to 'ContosoDemo10k' in Power BI Desktop

The answer reports the model name and an active connection. The first call to the MCP server raises a confirmation prompt. Read it: it is the only checkpoint before a change.

Step 7: verify the connection

Send these two prompts to the agent, one after the other:

List the tables and their row counts
Show me the relationships in the model

Both answers arrive in a few seconds. The chain works: Qwen Code, MCP server, Power BI Desktop.

Step 8: enable the write operations

The session started in read-only mode, so the next prompt would fail. Remove the restriction:

  1. Exit the client.

  2. Remove the read-only registration, in the command prompt:

    qwen mcp remove powerbi-modeling-mcp

  3. Register the server again without --readonly:

    qwen mcp add --scope user powerbi-modeling-mcp npx -- -y @microsoft/powerbi-modeling-mcp@latest --start
  4. Start qwen again and connect again, as in step 6.

Then send this prompt:

Create a measure that returns the Sales Amount of the previous year using the same format of the original measure.

The measure appears in Power BI Desktop without a refresh. Each write operation raises a confirmation prompt. The same approach applies to bulk operations, like format strings and display folders on hundreds of objects in a single request.

Step 9: enable the preview features for the report layer

The MCP server operates on the semantic model. The report layer requires a different tool, the Power BI report authoring skill, which works only on PBIP files in PBIR format. PBIP stands for Power BI Project, PBIR for Power BI enhanced report format. The skill cannot modify a .pbix file.

In Power BI Desktop, open File > Options and settings > Options > Preview features and enable these three options:

  • Power BI Project (.pbip) save option
  • Store reports using enhanced metadata format (PBIR)
  • Enable external tool access to Power BI Desktop through secure local APIs

The third option is the Power BI Desktop Bridge, and it is enabled by default. The report authoring skill uses it to reload the project and to capture a screenshot of a page, so that the agent verifies its own work. Verify that the option is checked.

Restart Power BI Desktop.

Step 10: save the sample as a project

Use File > Save as and choose the Power BI Project (*.pbip) file type. Power BI Desktop creates this structure:

ContosoDemo10k.pbip
ContosoDemo10k.SemanticModel/
ContosoDemo10k.Report/
.gitignore

The model is a set of TMDL files (Tabular Model Definition Language) and the report is a set of JSON files. Put the folder under source control and commit a baseline, so to undo a wrong operation with one command.

Step 11: install the report authoring skill

Git is required for this step. The repository is downloaded with git, and Windows does not include it. Install it, then close the command prompt and open it again.

Choose one of the two methods.

Option 1: the installer. Download it from git-scm.com/downloads/win and run it.

Option 2: WinGet. In the command prompt:

winget install --id Git.Git --source winget

The skills call two command-line tools. Install them in the command prompt:

npm install -g @microsoft/powerbi-report-authoring-cli@latest @microsoft/powerbi-desktop-bridge-cli@latest

The skill is part of the powerbi-authoring plugin of the skills-for-fabric repository, published by Microsoft. The plugin contains five skills: semantic model authoring, report planning, report design, report authoring, and report management.

Qwen Code is not one of the clients with a marketplace command for these skills, and Microsoft does not name it in the compatibility list. Two mechanisms of Qwen Code make the manual installation possible.

The first one is the instruction file. Qwen Code reads QWEN.md and AGENTS.md, and the repository publishes an AGENTS.md file in its root. Clone the repository inside the folder of the project:

git clone https://github.com/microsoft/skills-for-fabric.git C:\Demo\skills-for-fabric

The second one is the skills folder. Qwen Code discovers the skills in %USERPROFILE%\.qwen\skills and in .qwen\skills of the project, in the same SKILL.md format used by the repository. There is no install command, the discovery is by position, so copy the folders in the command prompt:

xcopy /E /I "C:\Demo\skills-for-fabric\plugins\powerbi-authoring\skills" "%USERPROFILE%\.qwen\skills"

Please, verify the folder names in the repository before you copy, because the layout changes between versions. The repository also has a skills folder in its root, which contains all the skills of the collection. The five skills of the report layer are the ones in the folder of the plugin.

Restart the client and list the skills:

/skills

This combination is not documented by Microsoft or by the Qwen Code project, and it can stop working with any update of the repository. Treat it as a manual installation and verify the result on the sample before you use it on a model that matters.

Step 12: connect the agent to the project

Start the client in the command prompt, in the folder that contains the .pbip file, so that the agent sees both the model folder and the report folder. Then send this prompt:

Open semantic model from PBIP folder 'C:\Demo\ContosoDemo10k.SemanticModel'

The MCP server manages the semantic model folder. The authoring skill reads and writes the report folder as files.

Step 13: create a report page

Create a report page with a line chart showing Sales Amount by Quarter, and a card showing the Sales Amount of the last year that has data.

Then ask the agent to validate the report, which checks the structure of the PBIR files, and open the .pbip file in Power BI Desktop. The skill runs this command, and you can run it yourself in the command prompt:

powerbi-report-author validate "C:\Demo\ContosoDemo10k.Report"

Save any manual change in Power BI Desktop before the agent iterates. The agent reads the files on disk and does not see the unsaved state. Editing in both places at the same time loses one set of changes.

The examples in the documentation use cards, bar charts, clustered column charts, tables, KPI cards, and slicers, and the skill converts the legacy card and matrix visuals into the modern cardVisual and pivotTable. There is no published list of the supported visuals, so expect some trial and error. Q&A, Bing maps, and filled maps are announced for deprecation, and Microsoft recommends avoiding them.

Configuration options

The command-line arguments of the MCP server go after -- in the qwen mcp add command, or in the args array of the JSON entry.

Option Default Description
--start required Starts the server.
--readwrite enabled Allows write operations, each one with a confirmation.
--readonly   Blocks all the write operations.
--skipconfirmation   Removes the confirmation prompts.
--compatibility PowerBI Set it to Full for Analysis Services databases.
--authmode interactive Set it to serviceprincipal for unattended scenarios.

For the service principal authentication, set AZURE_CLIENT_ID and AZURE_TENANT_ID in the environment of the server, with either AZURE_CLIENT_SECRET or AZURE_CLIENT_CERTIFICATE_PATH.

On a model that matters, run the first session with --readonly, as in step 4.

Alternative installation methods

Manual installation. Download the VSIX package of the Visual Studio Code extension of the MCP server, rename it with the .zip extension, extract it, and configure the path of the executable. This avoids the download that npx performs at every start:

{
  "mcpServers": {
    "powerbi-modeling-mcp": {
      "command": "C:\\MCPServers\\PowerBIModelingMCP\\extension\\server\\powerbi-modeling-mcp.exe",
      "args": ["--start"]
    }
  }
}

The cwd property sets the working folder of the server, and the client refuses to start when the folder does not exist. Write the Windows paths with a double backslash, as in the example, or with the forward slash.

Limitations

  • The MCP server operates on the semantic model, not on the report.
  • The report authoring skill operates on PBIP projects in PBIR format, not on a .pbix file.
  • Neither of them can do anything your permissions do not allow, because they operate with your identity.
  • Model metadata does not stay local: table names, column names, measure definitions, and query results are sent to the language model of the service you signed in to.
  • The MCP server, the report authoring skill, and the Power BI Desktop Bridge are all in preview. Behavior and tools can change before general availability.
  • The agent proposes and executes. The review is your responsibility.
  • The free tier of Qwen Code with a personal account was discontinued in April 2026. A paid key is part of the requirements.
  • The report authoring skill has no marketplace installation for Qwen Code. The manual path of step 11 is not covered by the documentation of Microsoft or of the project.

Troubleshooting

The qwen command is not found. Close and open the terminal again, so that it reads the updated path. With npm, verify that the global folder of npm is in the path.

The client asks for an authentication that you do not have. The free tier with a personal account was discontinued. Run /auth and configure a key of one of the supported providers.

The registration fails with Not enough non-option arguments: got 1, need at least 2. The double dash is before npx instead of after it, so the client reads one argument where it needs the name and the command. Write powerbi-modeling-mcp npx -- -y ..., as in step 4.

A prompt about Power BI returns an error 401, or another error of authentication. That error arrives from the provider of the model, and not from the MCP server. A local server started with npx communicates on the standard input and output: it has no token, and it cannot produce an error of HTTP. Send say hello, and if that fails too, the subject is the authentication of step 5 and the MCP server has nothing to do with it.

The key works when you test it, and the client refuses it. Read the configuration the client is using, with /about, and compare the address with the one of your console. An entry of the menu of /auth named after a commercial plan keeps its own address, and it wins over the variables of the environment and over the files .env. Run /auth again and choose the provider compatible with the OpenAI protocol, then write the address of your console. Consider also that a test on the list of the models proves nothing, because some services answer that list to any key: only a request of completion tells you whether a key is accepted.

The MCP server does not appear in the list of tools. Run qwen mcp list in the terminal, or /mcp in the client. If you registered the server in the project instead of the user scope, run qwen mcp approve and start a new session.

The server does not start and the message mentions the working folder. The cwd property points to a folder that does not exist. Remove it, or write the path with a double backslash.

The npm or the npx command is not found. Node.js is not installed, or the terminal was opened before the installation. Close the terminal, open it again, and run node --version. See step 1.

The git command is not found. Git is not installed, or the command prompt was opened before the installation. Install Git for Windows as in step 11, then close the command prompt and open it again.

The server starts and provides no tools. Verify that Node.js is installed and that npx runs. The first start downloads the package, so it takes longer than the following ones. Run npx -y @microsoft/powerbi-modeling-mcp@latest --help once in the command prompt, so that the package is already in the cache.

Cannot connect to Power BI Desktop. The file must be open, and the name in the prompt must match the title bar: ContosoDemo10k, not ContosoDemo10k.pbix. After a restart of Power BI Desktop the port changes. Connect again.

The write operations are rejected. You need write permission on the model, and the server must not run with --readonly. See step 8.

The agent reports that a command is not available when it validates the report. Install the two command-line tools of step 11, @microsoft/powerbi-report-authoring-cli and @microsoft/powerbi-desktop-bridge-cli, then restart the client.

The report authoring skill does not modify the report. It requires PBIP in PBIR format. Verify both preview features and save the project again, because enabling PBIR does not convert a project already saved.

The report changes do not appear in Power BI Desktop. Reload the project. Power BI Desktop shows the version loaded before. Verify the preview option of the Power BI Desktop Bridge, so that the agent reloads the project without your intervention.

The agent modifies objects you did not mention. Name the objects explicitly. For example, “add display folders to the measures in the Sales table” instead of “apply the best practices”.

Conclusions

Install Node.js, install Qwen Code, register the Power BI Modeling MCP server with one command, open a model in Power BI Desktop, connect with one prompt.

These are the rules we suggest applying:

  • Register the server in the user scope, so that it does not wait for an approval.
  • Verify the provider with /doctor before you blame the MCP server for a failure.
  • Register the server by its package name, instead of asking the agent to find it.
  • Verify the connection with a read-only prompt before any change.
  • Keep a backup of the model, or work on a PBIP project under source control.
  • Read the confirmation prompts.
  • Use --readonly for the first session on a model that matters.
  • Do not write the connection port in a script.
  • Open the folder of the project in the client, so that the model and the report are both visible to the agent.
  • For the report layer, use PBIP with PBIR, and save in Power BI Desktop before the agent iterates.

References

The content of this article was verified in September 2026, with the @microsoft/powerbi-modeling-mcp package installed from npm with the @latest tag. Command names, preview settings, and plan boundaries change over time, so the linked documentation is the authority.

Last update: Sep 13, 2026
In this page