Metadata-Version: 2.4
Name: nudg3-mcp
Version: 1.0.0
Summary: MCP server for Nudg3 brand visibility intelligence — query your AI search visibility from Claude, Cursor, or any MCP client
Project-URL: Homepage, https://nudg3.ai
Project-URL: Documentation, https://nudg3.ai/docs/mcp
Project-URL: Repository, https://github.com/NUDG3-AI/nudg3-mcp
Project-URL: Issues, https://github.com/NUDG3-AI/nudg3-mcp/issues
Author-email: Nudg3 <support@nudg3.ai>
License-Expression: MIT
Keywords: ai-search,brand-visibility,geo,llm-analytics,mcp,nudg3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: authlib>=1.6.11
Requires-Dist: cryptography>=46.0.7
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: python-multipart>=0.0.26
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Description-Content-Type: text/markdown

# nudg3-mcp

<!-- mcp-name: ai.nudg3/brand-intelligence -->

MCP server for [Nudg3](https://nudg3.ai) 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](https://app.nudg3.ai/api-keys).

### 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):

```json
{
  "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 |
|------|-------|-------------|
| `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 |

## 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

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

### Custom / programmatic

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

## Development

```bash
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
```
