mcp-server-steam

AI 를 활용해 생성된 프로젝트입니다.

FastMCP를 사용하여 Steam Web API와 통합하는 종합 MCP(Model Context Protocol) 서버입니다.

주요 기능

• 사용자 프로필 및 통계

  • 프로필 정보 (닉네임, 아바타, 계정 상세)
  • 친구 목록
  • 소유 게임 라이브러리
  • 플레이시간 데이터
  • 최근 플레이한 게임
  • Steam 레벨
  • 업적 진행상황

• 게임 정보 및 스토어

  • 게임 상세 정보 및 메타데이터
  • 스토어 가격 및 할인 정보
  • 뉴스 및 업데이트
  • 게임 검색
  • 특정 게임의 업적 데이터

• 커뮤니티 기능

  • Steam 워크샵 아이템
  • 사용자 리뷰
  • VAC 및 게임 밴 상태

PyPI에서 설치

PyPI에 게시된 후 다음과 같이 설치할 수 있습니다:

pip install mcp-server-steam

설치 후 다음과 같이 실행합니다:

mcp-server-steam

소스에서 설치

또는 소스 코드에서 직접 설치합니다:

1. 저장소 클론:

git clone <repository-url>
cd mcp-server-steam

1. uv로 의존성 설치:

uv sync

1. 패키지 설치:

uv pip install -e .

1. Steam Web API 키 발급:

   • https://steamcommunity.com/dev/apikey 방문
   • Steam 계정으로 로그인
   • 도메인 등록 후 API 키 복사

2. 환경 설정:

중요: .env 파일에 API 키를 설정해야 합니다.

# .env.example을 복사해서 .env 파일 생성
cp .env.example .env

# .env 파일을 텍스트 편집기로 열어서 STEAM_API_KEY 추가
# 예: STEAM_API_KEY=YOUR_API_KEY_HERE

# (선택사항) Steam ID를 기본값으로 설정하려면:
# STEAM_USER_ID=76561198XXXXXXXXXXX

API 키 발급: https://steamcommunity.com/dev/apikey

사용 방법

서버 실행

# PyPI에서 설치한 경우
mcp-server-steam

# 소스에서 개발 중인 경우
uv run python -m mcp_server_steam

서버가 STDIO 전송 방식으로 시작되며, Claude Desktop 같은 MCP 클라이언트에서 사용할 수 있습니다.

Claude Desktop Configuration

📖 자세한 설정 가이드: CLAUDE_CONFIG.md

PyPI에서 설치한 경우 (권장)

Claude Desktop 설정 파일에 추가:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "steam": {
      "command": "uvx",
      "args": ["mcp-server-steam"],
      "env": {
        "STEAM_API_KEY": "${STEAM_API_KEY}",
        "STEAM_USER_ID": "${STEAM_USER_ID}"
      }
    }
  }
}

또는 pip으로 설치한 경우:

{
  "mcpServers": {
    "steam": {
      "command": "mcp-server-steam",
      "env": {
        "STEAM_API_KEY": "${STEAM_API_KEY}",
        "STEAM_USER_ID": "${STEAM_USER_ID}"
      }
    }
  }
}

소스에서 개발하는 경우

{
  "mcpServers": {
    "steam": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_server_steam"],
      "cwd": "/path/to/mcp-server-steam",
      "env": {
        "STEAM_API_KEY": "${STEAM_API_KEY}",
        "STEAM_USER_ID": "${STEAM_USER_ID}"
      }
    }
  }
}

환경 변수 사용 (권장)

API 키를 직접 입력하는 대신 환경 변수를 사용하세요:

# ~/.zshrc 또는 ~/.zprofile에 추가
export STEAM_API_KEY="your_steam_api_key_here"

설정에서는:

"env": {
  "STEAM_API_KEY": "${STEAM_API_KEY}"
}

Claude Desktop 재시작

설정을 적용하려면 Claude Desktop을 완전히 종료했다가 다시 시작하세요.

MCP 클라이언트 설정

일반적으로는 PyPI 버전을 사용하는 것이 좋습니다:

{
  "mcpServers": {
    "steam": {
      "command": "uvx",
      "args": ["mcp-server-steam"],
      "env": {
        "STEAM_API_KEY": "${STEAM_API_KEY}",
        "STEAM_USER_ID": "${STEAM_USER_ID}"
      }
    }
  }
}

FastMCP CLI로 테스트

# 사용 가능한 도구 목록 보기
uv run fastmcp list src/mcp_server_steam/server.py

# 도구 호출 테스트
uv run fastmcp call src/mcp_server_steam/server.py get_user_profile steam_id=76561198000000000

사용 가능한 도구

프로필 도구

• get_user_profile - Steam 사용자 프로필 조회
• get_friends_list - 친구 목록 조회
• get_owned_games - 소유한 모든 게임 조회
• get_recently_played_games - 최근 플레이한 게임 조회
• get_steam_level - Steam 레벨 조회
• get_player_achievements - 특정 게임의 업적 진행상황 조회

게임 도구

• get_game_details - 스토어에서 게임 정보 조회
• get_game_news - 게임 뉴스 및 업데이트 조회
• get_global_achievement_percentages - 전체 업적 통계 조회
• search_games - Steam에서 게임 검색
• get_game_schema - 업적 및 통계 스키마 조회

커뮤니티 도구

• get_workshop_items - Steam 워크샵 아이템 조회
• get_workshop_item_details - 워크샵 아이템 상세 정보
• get_user_reviews - 게임 사용자 리뷰 조회
• get_player_bans - VAC 및 게임 밴 상태 조회

유틸리티 도구

• resolve_vanity_url - Vanity URL을 Steam ID로 변환

리소스

• steam://config - 서버 설정
• steam://supported-games - 일반적인 게임 App ID 목록

Steam ID vs App ID

• Steam ID (SteamID): 64비트 사용자 계정 ID (예: 76561198000000000)
• App ID (AppID): Steam 스토어에서의 게임 식별자 (예: CS2의 경우 730)

커스텀 프로필 URL을 Steam ID로 변환하려면 resolve_vanity_url을 사용하세요.

속도 제한 (Rate Limiting)

서버는 Steam API 제한을 준수하기 위해 속도 제한을 구현합니다:

• 분당 100회 요청
• 오류 발생 시 자동 지수 백오프
• 속도 제한 응답에 대한 적절한 에러 처리

프로젝트 구조

mcp-server-steam/
├── src/
│   └── mcp_server_steam/
│       ├── __init__.py
│       ├── __main__.py        # 메인 진입점
│       ├── server.py          # MCP 서버
│       ├── steam_client.py    # Steam API 클라이언트
│       ├── config.py          # 설정
│       └── tools/             # 도구 모듈
│           ├── __init__.py
│           ├── profile.py     # 사용자 프로필 도구
│           ├── games.py       # 게임 정보 도구
│           └── community.py   # 커뮤니티 도구
├── pyproject.toml             # 프로젝트 설정 및 의존성
├── README.md                  # 이 파일
├── .env                       # API 키 (git에 포함되지 않음)
└── .env.example               # 환경변수 템플릿

에러 처리

서버는 다음 경우에 명확한 에러 메시지를 제공합니다:

• 유효하지 않은 Steam ID 또는 App ID
• API 키 누락
• 속도 제한 초과
• 네트워크 오류
• Steam API 오류

AI 사용 예시

예시 1: 사용자 프로필 조회

사용자: "내 Steam 프로필 조회해줘"
AI: resolve_vanity_url을 호출하여 vanity URL을 Steam ID로 변환
AI: get_user_profile을 호출하여 프로필 정보 조회

예시 2: 게임 라이브러리 분석

사용자: "내 게임 목록 보여줘"
AI: get_user_profile로 Steam ID 획득
AI: get_owned_games로 소유 게임 목록 조회
AI: 플레이타임 기준으로 정렬하고 상위 게임 요약

예시 3: 게임 검색 및 상세 정보

사용자: "엘든 링 GO 정보 알려줘"
AI: search_games로 "ELDEN RING" 검색
AI: get_game_details로 상세 정보, 가격, 장르 조회

예시 4: 업적 확인

사용자: "내 염완의 왕 게임 업적이 어떻게 돼?"
AI: get_owned_games로 게임 목록 확인
AI: get_player_achievements로 염완의 왕 업적 조회
AI: get_global_achievement_percentages로 전체 플레이어 대비 비교

예시 5: 워크샵 모드 찾기

사용자: "스카이림 모드 추천해줘"
AI: search_games로 스타필드 스카이림(Skyrim, App ID: 72850) 검색
AI: get_workshop_items로 인기 모드 목록 조회
AI: get_workshop_item_details로 특정 모드 상세 정보 확인

AI를 위한 팁

1. 도구 사용 순서: resolve_vanity_url → get_user_profile → 다른 도구들
2. 데이터 효율성: include_app_info=True로 한 번에 게임 정보까지 가져오기
3. 오류 처리: Steam ID가 유효하지 않으면 vanity URL 변환 먼저 시도
4. 언어 설정: 한국 사용자를 위한 language="korean" 또는 language="english" 파라미터 활용

기여

기여를 환영합니다! 이슈나 풀 리퀘스트를 자유롭게 제출해 주세요.

참고 자료

• Steam Web API 문서
• FastMCP 문서
• Steam Community 개발자 포털

라이선스

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요