Skip to content

Claude Desktop Setup

This guide shows how to configure Claude Desktop to use bnerd as an MCP tool server.

Prerequisites

  • bnerd CLI installed and in your PATH
  • Claude Desktop installed
  • bnerd configured with API token and org-id

Configuration

Add the following to your Claude Desktop configuration file:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

Edit %APPDATA%\Claude\claude_desktop_config.json:

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bnerd": {
      "command": "bnerd",
      "args": ["mcp-server", "--read-only"],
      "env": {
        "BNERD_TOKEN": "your-api-token",
        "BNERD_ORG_ID": "your-organization-id",
        "BNERD_API_URL": "https://api.bnerd.net"
      }
    }
  }
}

Safety Mode Selection

Choose the appropriate safety mode for your use case:

"args": ["mcp-server", "--read-only"]
Mode Flag Recommended for
Read-only --read-only Daily use, exploring infrastructure
Non-destructive --non-destructive Creating resources with AI assistance
Full access --allow-writes Trusted automation, cleanup tasks

Warning

Use --allow-writes only when you trust the AI to make destructive changes. In read-only mode, the AI can explore your infrastructure safely without risk of modifying anything.

Adding Project Context

To enable project-scoped resources (servers, volumes, K8s), add the project ID:

{
  "mcpServers": {
    "bnerd": {
      "command": "bnerd",
      "args": ["mcp-server", "--non-destructive"],
      "env": {
        "BNERD_TOKEN": "your-api-token",
        "BNERD_ORG_ID": "your-organization-id",
        "BNERD_PROJECT_ID": "your-project-id",
        "BNERD_API_URL": "https://api.bnerd.net"
      }
    }
  }
}

Verification

After configuring, restart Claude Desktop. You should see bnerd tools available in the tools menu. Try asking Claude:

"List my DNS zones using the bnerd tools"

Troubleshooting

Tools not appearing:

  • Verify bnerd is in your PATH: which bnerd
  • Check the config JSON is valid
  • Restart Claude Desktop completely

Authentication errors:

  • Verify your token: BNERD_TOKEN=... bnerd whoami
  • Check the org-id is correct

Audit logging:

The MCP server logs all tool calls to stderr. View the logs in Claude Desktop's developer console or redirect stderr when running manually:

bnerd mcp-server --read-only 2>mcp-audit.log