Metadata-Version: 2.4
Name: bigspy-mcp
Version: 0.1.0
Summary: BigSpy ad intelligence MCP server - query BigSpy ad data via Chrome CDP
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: playwright>=1.40.0
Description-Content-Type: text/markdown

# BigSpy MCP

通过 Chrome CDP 查询 BigSpy 广告数据的 MCP 服务器。支持自动翻页、多平台汇总、批量导出。

## 安装

```bash
pip install bigspy-mcp
playwright install chromium
```

## 配置

### Claude Code（~/.claude/settings.json）

```json
{
  "mcpServers": {
    "bigspy": {
      "command": "bigspy-mcp"
    }
  }
}
```

### Claude Desktop

Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "bigspy": {
      "command": "bigspy-mcp"
    }
  }
}
```

### 通过 uvx（无需手动安装）

```json
{
  "mcpServers": {
    "bigspy": {
      "command": "uvx",
      "args": ["bigspy-mcp"]
    }
  }
}
```

> 首次运行时 uvx 会自动安装，但仍需手动运行 `playwright install chromium`。

## 使用前提

1. **安装 Google Chrome**
2. **登录 BigSpy**：首次使用时，工具会自动启动 Chrome 调试模式并打开 BigSpy，在 Chrome 里登录你的 BigSpy 账号即可。之后会记住登录状态。

## 使用方式

### 模式 1：抓当前搜索结果

在 Chrome 的 BigSpy 页面里选好筛选条件，然后对 Claude 说：

```
帮我把当前 BigSpy 搜索结果全部拉下来
```

### 模式 2：自然语言描述

```
帮我查一下 Upside 近30天在美国的广告投放
对比一下 Uber 和 Lyft 的广告投放
```

### 导出数据

```
导出成 CSV 放桌面
导出成 Excel 保存到 ~/Documents/
```

## 可用工具

| 工具 | 说明 |
|------|------|
| `check_connection` | 检查 Chrome 连接和 BigSpy 登录状态 |
| `grab_current_search` | 抓取当前 BigSpy 页面的搜索结果 |
| `search_ads` | 通过参数搜索广告数据 |
| `export_ads` | 导出数据为 CSV / JSON / Excel |
| `get_cross_platform_summary` | 获取多平台投放汇总 |
| `compare_advertisers` | 对比多个广告主 |
| `reset_connection` | 重置 Chrome 连接 |

## 注意事项

- 搜索消耗 BigSpy 的请求配额，工具会返回剩余配额
- 可查询的平台取决于你的 BigSpy 套餐
- Chrome 必须通过调试模式启动（工具会自动处理）
