npm package: @seo-console-org/mcp-server
Description: MCP server for SEO Console — expose Fix Packages, SEO issues, and recommendations to Cursor, Claude Code, Claude Desktop, and other MCP clients.
Latest version: 0.1.0

# @seo-console/mcp-server

**SEO Console MCP 서버** — Claude Code, Cursor, Claude Desktop 등 MCP 지원 도구에서 SEO Console 데이터에 직접 접근합니다.

개발자가 IDE를 떠나지 않고:
- SEO 이슈 목록 조회 & AI 권고사항 확인
- GSC 성과 데이터 분석 (웹/뉴스/디스커버)
- SEO 진단 실행 (100점 만점)
- URL 크롤링 & 이슈 감지
- Fix Package 관리 (조회/완료 처리)
- Core Web Vitals 모니터링
- 알림 확인 (트래픽 급락, 색인 탈락 등)

---

## 연결 방법

### 방법 1: 원격 HTTP (설치 불필요, 권장)

아무것도 설치할 필요 없이 URL과 API Key만으로 바로 연결됩니다.

**Claude Code** (`~/.claude/settings.json`):
```json
{
  "mcpServers": {
    "seo-console": {
      "type": "http",
      "url": "https://seo.aiinplanet.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_여기에_API_KEY"
      }
    }
  }
}
```

**Cursor** (Settings > MCP Servers > Add):
- Type: `http`
- URL: `https://seo.aiinplanet.com/mcp`
- Headers: `Authorization: Bearer sk_live_여기에_API_KEY`

### 방법 2: npm 패키지 설치 (stdio)

로컬에 설치하여 stdio로 실행합니다. 오프라인 환경이나 빠른 응답이 필요할 때.

```bash
npm install -g @seo-console/mcp-server
```

**Claude Code** (`~/.claude/settings.json`):
```json
{
  "mcpServers": {
    "seo-console": {
      "command": "seo-console-mcp",
      "env": {
        "SEO_CONSOLE_API_KEY": "sk_live_여기에_API_KEY",
        "SEO_CONSOLE_URL": "https://seo.aiinplanet.com"
      }
    }
  }
}
```

**Cursor** (Settings > MCP Servers > Add):
- Type: `stdio`
- Command: `seo-console-mcp`
- Environment:
  - `SEO_CONSOLE_API_KEY`: `sk_live_여기에_API_KEY`
  - `SEO_CONSOLE_URL`: `https://seo.aiinplanet.com`

---

## API Key 발급

1. [SEO Console 대시보드](https://seo.aiinplanet.com) 로그인
2. **설정 > API Keys** 페이지로 이동
3. **새 키 발급** 클릭
4. 스코프 선택 (전체 권장)
5. 발급된 `sk_live_...` 키를 복사하여 설정에 입력

> API Key는 발급 시에만 확인 가능합니다. 분실 시 새로 발급하세요.

---

## 사용 가능한 도구 (13개)

### 기본 조회

| 도구 | 설명 | 예시 질문 |
|------|------|-----------|
| `whoami` | 연결 상태 확인 | "MCP 연결 상태 확인해줘" |
| `list_workspaces` | 워크스페이스 목록 | "내 워크스페이스 보여줘" |
| `list_sites` | 사이트 목록 | "등록된 사이트 목록" |

### SEO 분석

| 도구 | 설명 | 예시 질문 |
|------|------|-----------|
| `get_performance` | GSC 성과 데이터 (클릭/노출/CTR/순위) | "최근 28일 성과 보여줘" |
| `get_cwv_scores` | Core Web Vitals 이력 | "CWV 점수 추이 보여줘" |
| `run_diagnosis` | SEO 종합 진단 (100점 만점) | "SEO 진단 실행해줘" |
| `crawl_url` | URL 크롤링 + 이슈 감지 | "이 페이지 SEO 상태 확인" |
| `list_issues` | 감지된 SEO 이슈 목록 | "CRITICAL 이슈 보여줘" |
| `list_alerts` | 알림 (트래픽 급락, 색인 탈락 등) | "최근 알림 있어?" |
| `list_recommendations` | AI 수정 권고사항 | "권고사항 보여줘" |

### Fix Package 관리

| 도구 | 설명 | 예시 질문 |
|------|------|-----------|
| `list_fix_packages` | 수정 패키지 목록 | "진행 중인 패키지 보여줘" |
| `get_fix_package` | 패키지 상세 (체크리스트 + AI 권고) | "이 패키지 상세 내용" |
| `mark_item_done` | 항목 완료 처리 | "이 항목 완료 처리해줘" |

---

## 실전 워크플로우

### 1. 사이트 현황 파악
```
"내 사이트들 현황 파악해줘"
→ list_sites → get_performance → list_alerts
```

### 2. SEO 문제 분석 & 수정
```
"SEO 진단하고 CRITICAL 이슈 보여줘"
→ run_diagnosis → list_issues (severity=CRITICAL) → list_recommendations
→ 코드 수정 → mark_item_done
```

### 3. 특정 페이지 점검
```
"https://example.com/about 페이지 SEO 확인해줘"
→ crawl_url → title, description, canonical, H1, 이슈 목록
```

### 4. 뉴스/디스커버 성과 비교
```
"웹/뉴스/디스커버 성과 비교해줘"
→ get_performance (WEB) → get_performance (NEWS) → get_performance (DISCOVER)
```

### 5. Fix Package 작업 진행
```
"진행 중인 Fix Package의 체크리스트 보여줘"
→ list_fix_packages (status=IN_PROGRESS) → get_fix_package
→ 수정 작업 진행 → mark_item_done (항목별 완료)
→ 모든 항목 완료 시 패키지 자동 COMPLETED
```

---

## 환경변수

| 변수 | 필수 | 설명 | 기본값 |
|------|------|------|--------|
| `SEO_CONSOLE_API_KEY` | stdio만 | API Key (`sk_live_...`) | - |
| `SEO_CONSOLE_URL` | 필수 | SEO Console URL | - |
| `SEO_CONSOLE_TIMEOUT_MS` | 선택 | API 타임아웃 (ms) | 15000 |
| `MCP_HTTP_PORT` | HTTP만 | HTTP 서버 포트 | 3100 |