bing-webmaster-ai-cli-mcp

# bing-webmaster-ai-cli-mcp

<!-- mcp-name: io.github.stufently/bing-webmaster-ai-cli-mcp -->

bing-webmaster-ai-cli-mcp gives an AI agent read access to what Bing knows about your sites — traffic, indexing, crawl issues, inbound links, keywords — and a write path you choose: direct by default, or reviewed plan-and-apply.

It ships a Python 3.12+ CLI and MCP server for the JSON Bing Webmaster Tools API,
plus protocol-correct IndexNow submission. SOAP and POX are deliberately absent.

## Choosing a write path

Read tools always execute immediately. For everything that changes Bing state, one
setting picks between two paths:

```console
export BING_WM_ALLOW_WRITES=true    # default: writes go straight through
export BING_WM_ALLOW_WRITES=false   # writes are planned and applied by a human
```

**If you are not sure, set it to `false`.** The default is convenience; `false` is the
safe answer, and here is the reason. An agent using this server also reads pages, anchor
text, crawl issues and search queries written by strangers. A confirmation an agent can
send is a confirmation prompt injection can send, so as long as the agent can write, a
poisoned string in someone else's anchor text can reach your Bing account. With
`false`, nothing an agent does changes Bing until you have read the plan and run
`bing-wm plan apply` yourself.

### Direct writes (default)

The MCP server advertises one-step `bing_<operation>` tools, and the CLI accepts:

```console
$ bing-wm submit-url example.com https://example.com/new-page --json
{"applied": true, "plan_id": "…", "operation": "submit_url", "result": null}
```

A direct write is not idempotent: retrying one records a new plan and sends the change
again. If a response is lost, read `audit.jsonl` or `bing-wm plan list` before repeating
the call.

### Reviewed writes (`BING_WM_ALLOW_WRITES=false`)

The server advertises `bing_plan_<operation>` instead. Those tools send nothing:

```console
$ bing-wm plan submit-url example.com https://example.com/new-page --json
{
  "plan_id": "…",
  "summary": "submit url https://example.com/new-page for https://example.com",
  "apply_with": "bing-wm plan apply …"
}
$ bing-wm plan apply PLAN_ID
Apply this plan? [y/N]: y
```

No MCP tool takes a plan ID, in either mode: a plan recorded for review is applied or
rejected only at the CLI, by you. A direct write applies the plan it creates in the same
call and never touches one somebody else recorded. The plan path stays available while
direct writes are on, so an agent can still propose a change for review.

### What both paths share

A direct write is the same code with the human step removed: it records the same durable
plan and goes through the same apply boundary. A readable plan record, an append-only
audit trail, one-shot application, expiry, Bing's own submission quota, a site denylist
(`BING_WM_DENIED_SITES`) and restart-persistent local limits
(`BING_WM_MAX_WRITES_PER_DAY`) apply to both.

If the applying process is killed and leaves a lock behind, the command
`bing-wm plan unlock PLAN_ID` verifies that the recorded PID is gone before recovering
it. An unfinished plan becomes `unknown_outcome` and cannot be applied again; the
recovery is audited.

## Install

```console
uvx --from "git+https://github.com/stufently/bing-webmaster-ai-cli-mcp.git" bing-webmaster-ai-cli-mcp
```

That one command starts the stdio MCP server. Every client block below runs the same
`uvx` command. Create an API key in Bing Webmaster Tools under Settings → API Access
and pass it as `BING_WM_API_KEY`. If you are not sure about writes, also set
`BING_WM_ALLOW_WRITES=false` — see [Choosing a write path](#choosing-a-write-path).

The package is not on PyPI yet. Until it is, `uvx bing-webmaster-ai-cli-mcp` (a PyPI
name, with no `--from`) does nothing useful. The command above is the install path.
PyPI publishing is switched off in `release.yml`: it is enabled by the repository
variable `PYPI_PUBLISH=true` once the PyPI Trusted Publisher is set up.

A checkout still installs with pip (Python 3.12+) and puts `bing-wm`,
`bing-webmaster-ai-cli-mcp` and `bing-webmaster-ai-cli-mcp-http` on `PATH`:

```console
python -m pip install "git+https://github.com/stufently/bing-webmaster-ai-cli-mcp.git"
export BING_WM_API_KEY='…'
bing-wm sites list
```

The supported matrix is Python 3.12, 3.13, and 3.14. Development and images use the
exact versions in `constraints.txt`; published dependencies remain compatible floors.
Never put a real key in the repository. See [configuration](docs/configuration.md) for
all settings.

## Example prompts

- Why did my site lose clicks last week?
- Which pages is Bing failing to crawl, and why?
- Is this URL indexed, and when did Bing last fetch it?
- Submit this new page to Bing, but let me review the change first.

## Add the MCP server to your AI client

Every JSON block below runs the same `uvx` command as [Install](#install).
`BING_WM_ALLOW_WRITES` is `false` here, so writes are planned and you apply them.
Remove that variable for direct writes — see
[Choosing a write path](#choosing-a-write-path). Keep the key in a user-level config,
not in a project file you commit. The server exposes 34 Bing read tools, one local
read-only tool (`bing_indexnow_key_plan`), plan inspection, and one write tool per
supported operation — direct `bing_<operation>` tools by default, or
`bing_plan_<operation>` tools when `BING_WM_ALLOW_WRITES=false`. It exposes no plan
application or rejection tool. Restart the server after changing the setting so the
client refreshes its tool list.

### Claude Code

Project file: `.mcp.json` in the project root.

```json
{
  "mcpServers": {
    "bing-webmaster": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/stufently/bing-webmaster-ai-cli-mcp.git",
        "bing-webmaster-ai-cli-mcp"
      ],
      "env": {
        "BING_WM_API_KEY": "your-api-key",
        "BING_WM_ALLOW_WRITES": "false"
      }
    }
  }
}
```

Or from the terminal:

```console
claude mcp add bing-webmaster --scope user \
  --env BING_WM_API_KEY=your-api-key --env BING_WM_ALLOW_WRITES=false \
  -- uvx --from "git+https://github.com/stufently/bing-webmaster-ai-cli-mcp.git" bing-webmaster-ai-cli-mcp
```

### Claude Desktop

File: `claude_desktop_config.json` — macOS
`~/Library/Application Support/Claude/claude_desktop_config.json`, Windows
`%APPDATA%\Claude\claude_desktop_config.json`, Linux
`~/.config/Claude/claude_desktop_config.json`.

```json
{
  "mcpServers": {
    "bing-webmaster": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/stufently/bing-webmaster-ai-cli-mcp.git",
        "bing-webmaster-ai-cli-mcp"
      ],
      "env": {
        "BING_WM_API_KEY": "your-api-key",
        "BING_WM_ALLOW_WRITES": "false"
      }
    }
  }
}
```

One click, without editing JSON: download the `.mcpb` from
https://github.com/stufently/bing-webmaster-ai-cli-mcp/releases/latest
and open it. Claude Desktop installs the extension and asks for the API key.
Direct writes stay off unless you turn Allow direct writes on. While they are off
the extension only records plans. Applying one needs the `bing-wm` CLI, which the
extension does not put on your `PATH`: install it with pip as in [Install](#install),
export the same key as `BING_WM_API_KEY` in that shell, then run `bing-wm plan apply`.

### Cursor

File: `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (this project).

```json
{
  "mcpServers": {
    "bing-webmaster": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/stufently/bing-webmaster-ai-cli-mcp.git",
        "bing-webmaster-ai-cli-mcp"
      ],
      "env": {
        "BING_WM_API_KEY": "your-api-key",
        "BING_WM_ALLOW_WRITES": "false"
      }
    }
  }
}
```

### Windsurf

File: `mcp_config.json` — macOS and Linux `~/.config/devin/mcp_config.json`
(or `$XDG_CONFIG_HOME/devin/mcp_config.json`), Windows
`%APPDATA%\devin\mcp_config.json`. Older builds read
`~/.codeium/windsurf/mcp_config.json`.

```json
{
  "mcpServers": {
    "bing-webmaster": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/stufently/bing-webmaster-ai-cli-mcp.git",
        "bing-webmaster-ai-cli-mcp"
      ],
      "env": {
        "BING_WM_API_KEY": "your-api-key",
        "BING_WM_ALLOW_WRITES": "false"
      }
    }
  }
}
```

### Zed

File: `settings.json` — Linux and macOS `~/.config/zed/settings.json`.

```json
{
  "context_servers": {
    "bing-webmaster": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/stufently/bing-webmaster-ai-cli-mcp.git",
        "bing-webmaster-ai-cli-mcp"
      ],
      "env": {
        "BING_WM_API_KEY": "your-api-key",
        "BING_WM_ALLOW_WRITES": "false"
      }
    }
  }
}
```

An optional Streamable HTTP entry point is also available once the package is on
`PATH` (the pip install above; `uvx` does not install a lasting command):

```console
export BING_WM_HTTP_BEARER_TOKEN='a-random-token-of-at-least-32-characters'
bing-webmaster-ai-cli-mcp-http
```

It refuses non-loopback bind addresses and unauthenticated requests.

## Common questions

### Which crawl issues does my site have?

```console
bing-wm crawl issues example.com --json
```

The result carries Bing's rows unchanged plus a category breakdown built from
Microsoft's `UrlWithCrawlIssues.CrawlIssues` flags — redirects, 4xx, 5xx, robots.txt
blocks, malware, DNS and timeout errors — with a count per category, a count per raw
`HttpCode`, and an `other` bucket so nothing Bing sends is dropped. A 4xx row is split
further into `http_404` or `http_403` from its own `HttpCode`, alongside the broad
`http_4xx` rather than instead of it. Bing has no `noindex` crawl-issue flag, so there
is no such category and this project does not invent one.

### How do I check if Bing has indexed my page?

```console
bing-wm index url example.com https://e