# How to Configure the DBX MCP Server for Windows Portable Builds

> Configure the DBX MCP server for Windows portable builds by setting the DBX_DATA_DIR environment variable. Learn how to point to your portable data folder for seamless operation.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: how-to-guide
- Published: 2026-07-10

---

**Set the `DBX_DATA_DIR` environment variable to the absolute path of the portable `data` folder containing `dbx.db` in your MCP server configuration.**

When running DBX as a Windows portable build, the SQLite database `dbx.db` resides in a local `data` directory rather than the standard `%APPDATA%` location. To enable the MCP server to access this portable database, you must explicitly configure the `DBX_DATA_DIR` environment variable. This ensures AI agents and MCP clients query the same connection store that the DBX desktop application uses, as implemented in the `t8y2/dbx` repository.

## Why Portable Builds Require Special Configuration

Standard DBX installations store the database at `%APPDATA%\com.dbx.app\dbx.db`. Portable builds keep the database next to the executable in a `data` sub-directory.

The MCP server checks `DBX_DATA_DIR` before falling back to the default location. Without this variable, the server attempts to read from `%APPDATA%`, resulting in empty or stale connection lists because it cannot find the portable build's database file.

## Configuring DBX_DATA_DIR in MCP Settings

The most reliable method is adding the environment variable to your MCP server configuration file.

### Minimal .mcp.json Configuration

Create or update your [`.mcp.json`](https://github.com/t8y2/dbx/blob/main/.mcp.json) file to include the absolute path to the portable data folder:

```json
{
  "mcpServers": {
    "dbx": {
      "command": "dbx-mcp-server",
      "env": {
        "DBX_DATA_DIR": "D:\\DBX_x64-portable\\data"
      }
    }
  }
}

```

This configuration directs the `dbx-mcp-server` binary to open `dbx.db` from the specified portable location rather than the default user profile path.

### Programmatic Start via npx

For development workflows or CI pipelines where you run the server from source without installing the global binary:

```json
{
  "mcpServers": {
    "dbx": {
      "command": "npx",
      "args": ["tsx", "packages/mcp-server/src/index.ts"],
      "cwd": "C:/path/to/your/dbx",
      "env": {
        "DBX_DATA_DIR": "C:\\DBX_x64-portable\\data"
      }
    }
  }
}

```

The `cwd` parameter ensures the Node.js process resolves the source files correctly, while `DBX_DATA_DIR` still overrides the data directory location.

## How the MCP Server Reads the Environment Variable

The DBX MCP server respects `DBX_DATA_DIR` across both the Rust native layer and the Node.js core utilities, ensuring consistent behavior between the desktop application and the MCP server.

### Rust Implementation

In [`src-tauri/src/data_dir.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/data_dir.rs) (line 34), the application checks `std::env::var_os("DBX_DATA_DIR")` before defaulting to the standard application data path. This logic ensures the portable override propagates through the entire DBX stack.

### Node.js Implementation

The [`packages/node-core/src/paths.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/paths.ts) file (line 5) mirrors this behavior by checking `process.env.DBX_DATA_DIR`. When the MCP server starts via [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts), it initializes the DBX core, which uses this path resolution to locate `dbx.db` and retrieve stored connections.

## Verifying the Configuration

After setting the environment variable, verify the server reads the correct database:

```bash

# Start the server (with DBX_DATA_DIR set in environment or config)

dbx-mcp-server

# In a separate terminal, query via the MCP client to verify connection visibility

dbx query local "SELECT name FROM sqlite_master WHERE type='table';" --json

```

If configured correctly, the query returns tables from the portable `dbx.db` rather than an empty result set or tables from the default `%APPDATA%` location.

## Summary

- Portable DBX builds store `dbx.db` in a local `data` folder, not `%APPDATA%\com.dbx.app\dbx.db`
- Set `DBX_DATA_DIR` to the absolute path of the `data` folder in your MCP configuration to override the default location
- The override works across Rust ([`src-tauri/src/data_dir.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/data_dir.rs)) and Node.js ([`packages/node-core/src/paths.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/paths.ts)) implementations
- Do not copy `dbx.db` to `%APPDATA%` to avoid stale data and synchronization issues

## Frequently Asked Questions

### Can I use a relative path for DBX_DATA_DIR?

No, always use an absolute path. The Rust `std::env::var_os` and Node.js `process.env` resolve the string literally, and relative paths may resolve against the MCP client's working directory rather than the portable build location, causing the server to fail to locate `dbx.db`.

### What happens if DBX_DATA_DIR points to the wrong folder?

The MCP server will fail to locate `dbx.db` and fall back to creating or accessing a database in the default `%APPDATA%\com.dbx.app\` location. This results in missing connections and configurations from your portable build, as the server reads a different database file than the desktop UI.

### Does this configuration affect the DBX desktop UI?

No, the desktop UI reads the same `DBX_DATA_DIR` variable. When you set this environment variable system-wide or in the context where both applications run, they share the same data directory automatically. This ensures the MCP server and the DBX GUI remain synchronized.

### Where is the official documentation for MCP server configuration?

The primary documentation resides in [`packages/mcp-server/README.md`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/README.md) under the section "For Windows portable builds" and in `docs/content/docs/mcp.mdx` on the DBX repository at `t8y2/dbx`. These files provide the same environment variable guidance for configuring Windows portable builds.