nudg3-mcp

nudg3-mcp

MCP server for Nudg3 brand visibility intelligence. Query your brand's AI search visibility from Claude Desktop, Cursor, Windsurf, or any MCP client.

Quickstart

1. Get an API key

Create one at app.nudg3.ai/api-keys.

Two key types (since 1.1.0):

• Workspace-scoped key — bound to one workspace. The default for single-brand customers. Every tool just works; you don't pass workspace_id.
• Agency / company-scoped key — bound to an agency or a company that owns multiple workspaces. Use list_workspaces first, then pass workspace_id to other tools. If the key only authorises one workspace the auto-resolver picks it for you; if it authorises many, the error response tells the LLM which UUIDs are available so it can ask you.

2. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "nudg3": {
      "command": "uvx",
      "args": ["nudg3-mcp"],
      "env": {
        "NUDG3_API_KEY": "nudg3_live_ak_..."
      }
    }
  }
}

3. Ask questions

• "What's my brand visibility score this week?"
• "Compare my visibility across ChatGPT and Gemini"
• "Which sources cite my brand most?"
• "Export my dashboard data for the last 30 days"

Tools

Tool	Scope	Description
list_workspaces	read:analytics	New in 1.1.0. Portfolio discovery for agency/company keys. Workspace keys see a single-element list.
get_overview	read:analytics	Health check: organic + branded visibility, trends, alerts, suggested investigations
analyze_competitors	read:analytics	Organic competitive rankings, position gaps, fastest movers
analyze_prompts	read:analytics	Prompt-level performance by funnel stage; auto-resolves your primary brand
analyze_sources	read:analytics	Top cited domains, type distribution, content gap detection
analyze_responses	read:analytics	Provider-grouped response samples, sentiment patterns
query_metrics	read:analytics	Composable analytics query with measures, dimensions, filters
get_metric_catalog	read:analytics	Discover available measures, filters, and export datasets
export_data	export:data	CSV export for chat responses, sources, dashboard, prompts
get_reports	read:insights	List or fetch visibility audit reports
get_insights	read:insights	AI-generated opportunities, threats, and recommendations from a report
get_actions	read:insights	Workspace action items with priority, effort, and impact

Since 1.1.0, every analytics/insights/export tool accepts an optional workspace_id argument. Workspace-scoped key callers can omit it. Agency/company-scoped key callers pass the UUID returned by list_workspaces — when only one workspace is accessible, it's auto-resolved.

Environment Variables

Variable	Required	Default	Description
NUDG3_API_KEY	Yes	—	Your Nudg3 API key
NUDG3_API_URL	No	https://api.nudg3.ai	API base URL
NUDG3_TIMEOUT	No	30	HTTP timeout in seconds

Other MCP Clients

Cursor

{
  "mcpServers": {
    "nudg3": {
      "command": "uvx",
      "args": ["nudg3-mcp"],
      "env": {
        "NUDG3_API_KEY": "nudg3_live_ak_..."
      }
    }
  }
}

Custom / programmatic

pip install nudg3-mcp
NUDG3_API_KEY=nudg3_live_ak_... nudg3-mcp

Development

git clone https://github.com/NUDG3-AI/nudg3-mcp-server.git
cd nudg3-mcp-server
python -m venv venv && source venv/Scripts/activate
pip install -e ".[dev]"
pytest