How to Configure the DBX MCP Server for Windows Portable Builds

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 file to include the absolute path to the portable data folder:

{
  "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:

{
  "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 (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 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, 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:

# 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) and Node.js (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}