seo-audit-mcp

Claude(또는 모든 MCP 클라이언트)가 라이브 웹사이트의 기술적 SEO를 감사할 수 있게 해주는 MCP 서버입니다: 사이트맵 적용 범위, 페이지별 문제, 리다이렉트 체인.

평범한 언어로 요청하세요 — "mortgagecalculatortools.com을 감사하고 Google에 절대 알려지지 않은 페이지를 알려줘" — 그러면 모델이 도구를 호출하고, 사이트를 크롤링하며, 구체적인 답변을 제공합니다.

해결하는 문제

사이트의 sitemap.xml은 Google에 어떤 페이지가 존재하는지 알리는 방법입니다. 페이지가 거기서 누락되어도 오류도 경고도 발생하지 않습니다. 단지 노출이 누적되지 않을 뿐입니다. 수동으로 확인하려면 파일 시스템 목록과 XML 파일을 비교(diff)해야 하므로, 실제로는 아무도 하지 않습니다.

사례 연구: 25페이지 누락이 사실은 정확했다

이 도구를 처음 적용한 사이트에는 디스크에 HTML 파일 125개, 사이트맵에 URL 100개가 있었다. 25페이지 누락은 버그로 기록되어 누군가에게 배정되는 종류의 발견입니다.

한 번의 sitemap_coverage 호출로 누락이 드러났고, 샘플에 대한 한 번의 audit_urls 호출로 설명되었습니다: 25개 페이지 모두 <meta name="robots" content="noindex, follow">를 포함하고 있었습니다. 이들은 의도적으로 색인에서 제외된 두 콘텐츠 클러스터였고, 사이트맵이 이를 생략한 것은 완전히 정확했습니다. 이후 파일 시스템과 대조해 확인한 결과: 디스크에 25개의 noindex 페이지가 있었고, 사이트맵에서 빠진 것도 같은 25개였으며, 잘못 포함된 noindex 페이지는 0개였습니다. 완벽한 일관성입니다.

그것이 유용한 결과입니다. 단순한 커버리지 숫자("125 vs 100")만으로는 결함으로 읽혀 누군가의 하루를 소모하게 합니다. 하지만 커버리지에 페이지별 noindex 상태를 더하면 그 질문은 1분 만에 해결됩니다. 이 도구는 실제 누락을 찾는 것만큼이나 잘못된 경보를 제거하는 데도 가치가 있습니다 — 그래서 audit_urls는 단순히 URL 개수만 세지 않고 페이지마다 noindex를 보고합니다.

도구

모든 도구는 페이지별 issues 목록과 집계된 issue_summary를 포함한 구조화된 JSON을 반환하므로, 모델은 원시 HTML을 다시 읽는 대신 숫자를 기준으로 추론할 수 있습니다.

설치

pip install -e .

Python 3.10+가 필요합니다. 의존성: mcp>=2.0.0, httpx.

Claude Code에 연결하기

프로젝트의 .mcp.json에 추가하세요(전역 사용 시 ~/.claude.json):

{
  "mcpServers": {
    "seo-audit": {
      "command": "python",
      "args": ["-m", "seo_audit_mcp"]
    }
  }
}

Claude Desktop의 경우 동일한 블록을 claude_desktop_config.json에 넣습니다.

그런 다음 그냥 요청하세요:

https://example.com/sitemap.xml의 사이트맵을 가져와서 처음 20개 URL을 감사하고, 이슈를 빈도별로 요약해 줘.

직접 실행하기

python -m seo_audit_mcp        # stdio transport

설계 노트

강조할 가치가 있는 세 가지 결정 사항이 있습니다. 이는 데모와 클라이언트 프로덕션 사이트에 사용할 수 있는 도구의 차이를 만듭니다:

크롤링은 구조적으로 속도가 제한됩니다. fetch_many는 최대 16개의 동시 요청으로 제한된 asyncio.Semaphore 뒤에서 실행되며, 모든 도구는 입력을 제한합니다. 그 상한선이 없다면 500-URL 사이트맵은 한 번에 500개의 소켓을 열고 대상 호스트에 공격으로 읽힐 수 있습니다. 크롤링은 대상 사이트가 부담하는 비용이므로, 상한선은 도구 표면에서 위로 구성할 수 없습니다.

가져오기 실패가 실행을 중단시키지 않습니다. fetch_one은 httpx.HTTPError를 잡아 예외를 발생시키는 대신 반환된 PageAudit에 기록합니다. 200-URL 크롤링에서 호스트 하나가 죽어도 199개의 좋은 결과를 잃는 대신 한 행만 저하됩니다.

파싱은 의도적으로 관대합니다. 실제 HTML은 잘못된 형식인 경우가 많아서 크롤링 중에 예외를 던지는 엄격한 파서는 오히려 부담입니다. 추출기들은 예외를 던지는 대신 None을 반환하는 허용적인 정규표현식입니다. 단, 함정은 처리합니다: <script>와 <style> 본문은 단어 수 계산과 제목 추출 전에 제거되므로 JS 문자열 리터럴 안의 <h1>은 제목으로 계산되지 않으며, 상대 canonical은 페이지 URL을 기준으로 해석됩니다.

normalize_url은 의도적으로 후행 슬래시를 제거하지 않습니다: /a와 /a/는 실제로 다른 페이지일 수 있으며, 이를 합치면 이 도구가 드러내기 위해 존재하는 중복 콘텐츠 문제가 숨겨질 수 있습니다.

테스트

pip install -e ".[dev]"
pytest

테스트 스위트는 네트워크 없이 실행됩니다 — HTTP는 httpx.MockTransport를 통해 실행되므로 CI와 비행기 안에서도 작동합니다. 프로덕션에서 문제가 되는 파싱 엣지 케이스를 다룹니다: 스크립트에 포함된 제목, 네임스페이스 없는 사이트맵, 상대 canonical, 스타일이 적용된 HTML 404를 200 상태로 반환하는 사이트맵 URL, 그리고 "제목 누락"으로 잘못 보고되는 비-HTML 콘텐츠 타입.

라이선스

MIT