mcp-windbg/docs/reference/clients.md

# Client configuration

`mcp-windbg` works with any MCP client. Below are ready-to-paste snippets for the common
ones. Install the server first, then point the client at it:

```bash
pip install mcp-windbg
```

All snippets set `_NT_SYMBOL_PATH` so stack traces resolve against the Microsoft symbol
server. Adjust the path or add more locations as needed. For running from a checkout, see
[Development](../development.md); for `uvx`, see [Other install methods](#other-install-methods).

## Claude Code

### Server with uvx

The [uvx plugin](plugin.md#server-with-uvx) is the shortest
path. It needs no `pip install` and no MCP configuration:

```text
/plugin marketplace add svnscha/mcp-windbg
/plugin install mcp-windbg-uvx@mcp-windbg
```

This plugin provides the eleven tools. [Skills](#skills-for-an-existing-server) and
[agents](#agents-for-an-existing-server) are optional separate installs.
The plugin runs the server with `uvx`, so it needs
[uv](https://docs.astral.sh/uv/) on `PATH`; it pins the server version so the plugin and the
server it drives stay in step.

Symbols work out of the box: the plugin supplies the Microsoft symbol server as a **default**
for `_NT_SYMBOL_PATH`. If you already have that variable set, your value wins and the default is
ignored, so a symbol path you tuned yourself is never overwritten.

### Registering the server directly

Register the server with `claude mcp add`. The `-s user` scope makes it available in every
project; drop it to scope the server to the current project only. Everything after `--` is
the command Claude Code runs:

```bash
claude mcp add mcp-windbg -s user -e _NT_SYMBOL_PATH="SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols" -- python -m mcp_windbg
```

Claude Code records the server in `.claude.json`:

```json title=".claude.json"
{
    "mcpServers": {
        "mcp-windbg": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "mcp_windbg"],
            "env": {
                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
            }
        }
    }
}
```

Add server options such as a [filter script](../scenarios/redaction.md) after the command,
for example `-- python -m mcp_windbg --filter-script C:\filters\pii_redaction.py`. Run
`claude mcp list` to confirm it connected.

### Skills for an existing server

After installing the uvx plugin or registering your server, optionally add the four workflows with the
[skills-only plugin](plugin.md#skills-for-an-existing-server):

```text
/plugin marketplace add svnscha/mcp-windbg
/plugin install mcp-windbg-skills@mcp-windbg
```

Use `/mcp-windbg-skills:analyze-dump` to start. The plugin uses your existing
connection, including an HTTP service, and does not require uv or change the
server's launch command, symbol settings, or version.

### Agents for an existing server

```text
/plugin marketplace add svnscha/mcp-windbg
/plugin install mcp-windbg-agents@mcp-windbg
```

Ask for `mcp-windbg-agents:crash-analyst` to investigate a dump through your
existing connection. This [agents plugin](plugin.md#agents-for-an-existing-server)
works independently of the skills plugin and does not install a server.

## Claude Desktop

Add to `claude_desktop_config.json` (at `%APPDATA%\Claude\claude_desktop_config.json`):

```json title="claude_desktop_config.json"
{
    "mcpServers": {
        "mcp-windbg": {
            "command": "python",
            "args": ["-m", "mcp_windbg"],
            "env": {
                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
            }
        }
    }
}
```

Restart Claude Desktop completely after saving. For background, see
[Connect local MCP servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers).

## VS Code (GitHub Copilot)

Create `.vscode/mcp.json` in your workspace, or use **MCP: Open User Configuration** (press
++f1++) to make it available everywhere:

```json title=".vscode/mcp.json"
{
    "servers": {
        "mcp_windbg": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "mcp_windbg"],
            "env": {
                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
            }
        }
    }
}
```

Then enable MCP: settings (++ctrl+comma++) -> search **MCP** -> enable **Model Context
Protocol** in Copilot Chat, and restart VS Code.

To pass server options such as a [filter script](../scenarios/redaction.md) or a custom CDB
path, add them to `args`:

```json
"args": ["-m", "mcp_windbg",
         "--cdb-path", "C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\cdb.exe"]
```

## GitHub Copilot CLI

Edit `C:\Users\{username}\.copilot\mcp-config.json`. `"tools": ["*"]` enables all of the
server's tools:

```json title="mcp-config.json"
{
    "mcpServers": {
        "mcp-windbg": {
            "type": "local",
            "command": "python",
            "args": ["-m", "mcp_windbg"],
            "tools": ["*"],
            "env": {
                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
            }
        }
    }
}
```

## Autohand Code

[Autohand Code](https://github.com/autohandai/code-cli) registers stdio servers with
`autohand mcp add <name> <command>`. Add `--scope project` to keep the registration in the
current workspace instead of the user profile:

```bash
autohand mcp add mcp-windbg python -m mcp_windbg
```

Autohand has no flag for a per-server `_NT_SYMBOL_PATH`; the server inherits the environment
that launched Autohand. Set `_NT_SYMBOL_PATH` in that shell (or system-wide) before starting
Autohand so stack traces resolve.

## HTTP transport

To run the server separately and connect over HTTP, start it with the
[streamable-http transport](cli.md#transports):

```bash
mcp-windbg --transport streamable-http --host 127.0.0.1 --port 8000
```

Then point the client at the endpoint:

```json
{
    "servers": {
        "mcp_windbg_http": {
            "type": "http",
            "url": "http://localhost:8000/mcp"
        }
    }
}
```

This transport has no authentication, so keep it on localhost or a trusted network. See
[Debug from another machine](../scenarios/http-service.md) for the full workflow.

## Other install methods

The snippets above use a pip install, which is the simplest path. Three alternatives:

### Standalone executable

`mcp-windbg.exe` is attached to every [release](https://github.com/svnscha/mcp-windbg/releases).
It carries its own Python interpreter and every dependency, so nothing needs installing and no
Python has to be present. `cdb.exe` is still a prerequisite.

Download it, put it somewhere stable, and point the client straight at it:

```json
{
    "servers": {
        "mcp_windbg": {
            "type": "stdio",
            "command": "C:\\tools\\mcp-windbg.exe",
            "env": {
                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
            }
        }
    }
}
```

No `args` are needed. Command-line options work as usual, so
`"args": ["--cdb-path", "C:\\dbg\\cdb.exe"]` is still available.

The release also publishes a `SHA256SUMS` file, and the executable is code signed. Both are
worth checking:

```powershell
(Get-FileHash .\mcp-windbg.exe -Algorithm SHA256).Hash   # compare with SHA256SUMS
Get-AuthenticodeSignature .\mcp-windbg.exe | Format-List Status, SignerCertificate
```

`Status` should read `Valid`.

!!! note "Why the signature says Liasoft GmbH"
    The project is written by Sven Scharmentke and the signing certificate is sponsored by
    Liasoft GmbH, so Windows names Liasoft GmbH as the verified publisher while the file's
    own details say Sven Scharmentke. The executable's `Comments` field states the same.

With `uvx`, which fetches and runs the server on demand with nothing installed first. Swap the
`command` and `args` of any snippet above for:

```json
{
    "command": "uvx",
    "args": ["--from", "git+https://github.com/svnscha/mcp-windbg", "mcp-windbg"]
}
```

From source (development):

```bash
git clone https://github.com/svnscha/mcp-windbg.git
cd mcp-windbg
python -m venv .venv
.\.venv\Scripts\activate
pip install -e .
```

```json
{
    "servers": {
        "mcp_windbg": {
            "type": "stdio",
            "command": "${workspaceFolder}/.venv/Scripts/python",
            "args": ["-m", "mcp_windbg"]
        }
    }
}
```