Steam Personal + Store MCP

로컬에서 실행되는 Steam MCP Server입니다. 기본적으로 도메인별로 구성된 12개의 복합 tool을 노출합니다.

할 수 있는 작업

개인 데이터

player는 Profile, 현재 게임 및 공개 설정을 조회합니다. library는 게임 라이브러리, 플레이 시간, 최근 플레이, backlog, 접은 게임 및 복귀 후보를 조회합니다. achievements는 업적 상세, 완료율 및 최근 해금을 조회합니다. friends는 친구와 공개된 공동 게임을 조회합니다.

스토어, 할인 및 위시리스트

store는 상세 정보 검색, 게임 비교 및 DLC 확인을 수행합니다. deals는 특가, 대폭 할인 및 세일을 조회합니다. wishlist는 위시리스트, 가격 내역, 가격 인하, 출시 변경, 그리고 근거가 있는 buy / wait / skip 제안을 확인합니다.

추천 및 통합 게임 프로필

recommendations는 스토어 후보, 유사 게임, 신작, backlog 및 라이브러리 중복도 분석을 리콜합니다. 후보의 candidate_score는 검색 우선순위만 나타내며, 최종 적합도나 구매 신뢰도가 아닙니다. 최종 판단은 이를 호출하는 AI에게 맡깁니다.

game_intel(action="snapshot")은 한 게임의 다음 정보를 요약합니다:

• 개인 보유 상태, 총 플레이 시간, 최근 플레이 시간, 마지막 플레이 및 업적.

• 현재 가격, 정가, 할인율, MCP가 관찰한 가격 내역.

• 전체 평가, 최근 평가, 평가 수 및 사용 가능한 7/30/90일 추세.

• Steam Deck 상태, Workshop 지원, 현재 플레이어 수 및 해석 가능한 인기 지표.

• 출시일, 업데이트/build 정보, DLC, 보유한 DLC 및 누락된 DLC.

• 로컬 설치 경로, SizeOnDisk, 실제 디렉터리 크기 및 shadercache. Windows의 compatdata는 명시적으로 not_applicable로 표시됩니다.

로컬 Steam 및 안전한 정리

local_steam은 Windows의 libraryfolders.vdf, appmanifest 파일, 설치된 게임 및 디스크 점유를 읽습니다. storage_cleanup은 scan, preview, clean의 3단계로 나뉘며, scan은 절대 삭제하지 않습니다. clean은 반드시 appids, targets를 명시하고 confirm=true를 전달해야 합니다. shadercache는 저위험, compatdata는 기본적으로 고위험이며 Windows 첫 버전에서는 적용되지 않습니다.

Related MCP server: gamelibs-mcp

복합 tool / action

player: profile | currently_playing | visibility
library: search | stats | most_played | recent | abandoned | never_played | low_playtime | backlog | return_to | game
achievements: details | summary | recent | almost_completed | completion_candidates
friends: list | playing | activity | shared
store: search | details | compare | dlc
deals: specials | deep_discounts | search_sales | summary
wishlist: list | sales | best_deals | price_history | price_drops | release_watch | buy_advice | purchase_candidates
recommendations: store | similar | new_releases | library | backlog | return_to | next | overlap | pick
activity: record | sessions | recent_sessions | year_review | game_change_history
game_intel: snapshot | update_impact
local_steam: scan | installed | disk_usage
storage_cleanup: scan | preview | clean

프로젝트 자체는 외부 LLM을 호출하지 않습니다. 데이터를 읽고, 필터링하고, 집계하고, 관찰 결과를 기록하고 구조화된 증거를 반환하는 역할을 하며, 최종 추천 판단은 상위 모델이 수행합니다.

빠른 시작

다음 명령은 Windows PowerShell에 적용됩니다.

1단계: 프로젝트 디렉터리로 이동

GitHub에서 다운로드:

git clone https://github.com/megabaka404/steam-personal-mcp.git
Set-Location steam-personal-mcp

프로젝트가 이미 로컬에 있는 경우:

Set-Location -LiteralPath '你的项目目录\steam-personal-mcp'

2단계: 환경 생성 및 의존성 설치

프로젝트에는 Python 3.10 이상이 필요합니다.

py -3 -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

3단계: Steam 구성

구성 파일을 복사하고 편집합니다:

Copy-Item .env.example .env
notepad .env

최소한 다음을 입력합니다:

STEAM_API_KEY=你的Steam_Web_API_Key
STEAM_ID=你的SteamID64

API Key 받기:

https://steamcommunity.com/dev/apikey

참고:

• STEAM_ID는 SteamID64여야 합니다.

• Steam Profile과 Game Details가 외부에 공개되어 있어야 합니다. 그렇지 않으면 개인 데이터를 읽지 못할 수 있습니다.

• 기본적으로 중국 지역 스토어를 사용합니다. 스토어 가격은 STEAM_STORE_COUNTRY와 STEAM_STORE_LANGUAGE에 따라 달라집니다.

선택적 구성:

STEAM_MCP_HOST=127.0.0.1
STEAM_MCP_PORT=8789
STEAM_MCP_COMPACT_TOOLS=true
STEAM_MCP_LEGACY_TOOLS=false
STEAM_STORE_COUNTRY=cn
STEAM_STORE_LANGUAGE=english
STEAM_HISTORY_DB=data/steam_history.sqlite3

기본적으로 12개의 복합 tool이 활성화됩니다. 기존의 세분화된 tool을 계속 사용해야 하는 경우 다음을 설정할 수 있습니다:

STEAM_MCP_COMPACT_TOOLS=false
STEAM_MCP_LEGACY_TOOLS=true

Steam 스토어 지역 전환

스토어 지역은 Steam의 두 자리 국가/지역 코드를 사용하며, .env의 STEAM_STORE_COUNTRY로 수정합니다. 수정 후 MCP 서비스를 재시작해야 적용되며, 기본값은 중국 지역입니다.

중국 지역:

STEAM_STORE_COUNTRY=cn
STEAM_STORE_LANGUAGE=schinese

미국 지역:

STEAM_STORE_COUNTRY=us
STEAM_STORE_LANGUAGE=english

일본 지역:

STEAM_STORE_COUNTRY=jp
STEAM_STORE_LANGUAGE=japanese

기타 일반적인 코드로는 gb(영국), de(독일), fr(프랑스)이 있습니다. 프로젝트는 자동 환율 변환을 수행하지 않습니다. 지역을 전환하면 가격, 통화, 할인 및 일부 Store 검색 결과가 모두 변경될 수 있습니다.

4단계: 먼저 Mock 모드로 서비스 확인

Mock 서비스 시작:

python server.py --mock

다른 PowerShell 창을 열어 확인:

Invoke-WebRequest http://127.0.0.1:8789/health | Select-Object -ExpandProperty Content
Invoke-WebRequest http://127.0.0.1:8789/debug/status | Select-Object -ExpandProperty Content

헬스 체크가 성공하는 것을 확인한 후 실제 Steam 모드를 시작합니다.

5단계: 실제 서비스 시작

HTTP 모드:

python server.py

MCP 주소:

http://127.0.0.1:8789/mcp

stdio 모드:

python server.py --stdio

Mock 데이터가 필요한 경우:

python server.py --stdio --mock

참고: 기본값은 중국 지역입니다. 지역을 변경하려면 터미널에서 MCP를 시작하기 전에 다음을 입력합니다: $env:STEAM_STORE_COUNTRY="cn" $env:STEAM_STORE_LANGUAGE="schinese" 다른 국가나 지역도 동일한 방식으로 코드를 수정하면 됩니다.

MCP 클라이언트 구성

클라이언트가 Streamable HTTP를 지원하는 경우 다음을 추가합니다:

{
  "mcpServers": {
    "steam-personal": {
      "url": "http://127.0.0.1:8789/mcp"
    }
  }
}

/health를 MCP 주소로 사용하지 마세요. 이는 헬스 체크 인터페이스일 뿐입니다.

stdio 클라이언트는 python server.py --stdio를 시작하는 명령으로 구성하고, 프로젝트 가상 환경의 Python을 사용합니다.

연결 성공 후 직접 질문할 수 있습니다:

我的游戏库里有哪些几乎没玩过的游戏？
Darkest Dungeon 现在值得买吗？
把我的愿望单按当前折扣列出来。
根据我最近玩过的游戏召回 15 个候选，但只给证据，不要直接替我下结论。

데이터 출처 및 제한 사항

• 개인 데이터는 주로 Steam Web API에서 가져오며, 스토어 데이터는 Steam Store 인터페이스에서 가져옵니다.

• Steam 프로필, 게임 상세 또는 통계의 개인정보 보호 설정으로 인해 데이터가 누락될 수 있습니다.

• 일부 게임은 업적, 플레이어 통계 또는 공개 평가를 지원하지 않으며, 관련 필드는 비어 있을 수 있습니다.

• 스토어 인터페이스는 완전하고 안정적인 Steam 전체 카탈로그가 아닙니다. 검색 결과는 지역, 언어 및 인터페이스 제한의 영향을 받을 수 있습니다.

• 가격, 통화 및 할인은 구성된 스토어 지역에 따라 반환됩니다.

• 평가 데이터는 Steam 인터페이스가 안정적으로 제공할 때만 채워지며, 완전성을 위해 추측하지 않습니다.

• 업적 읽기에 실패해도 "모두 미해금"으로 위조하지 않습니다.

• 가격 내역, 플레이 session 및 연간 리뷰는 이 MCP의 로컬 관찰 결과이며, Steam 공식 전체 내역이 아닙니다.

프로젝트 구조

server.py          服务入口
config.py          环境变量和启动参数
runtime.py         HTTP/stdio 运行时
clients/           Steam API 和 Store 客户端
services/          业务逻辑、推荐、历史记录
tools/             MCP 工具实现
models/            Pydantic 数据模型
tests/             自动化测试
data/              本地历史数据库目录

라이선스

저장소의 라이선스 파일을 기준으로 합니다. Steam 데이터는 Steam/Valve 서비스의 콘텐츠입니다. 이 프로젝트는 공개 인터페이스를 읽고 로컬에서 정리 및 분석만 수행합니다.

Store 검색 결과가 왜 완전하지 않나요?

공개 Store search / featured endpoint는 Steam 상품 전체 데이터베이스가 아닙니다.

따라서 다음 tool은 제한된 후보 집합을 반환합니다:

search_store
search_sales
new_releases_for_me
recommend_store_for_me

특정 게임을 조회해야 하는 경우 AppID를 우선 사용하세요.

가격 지역이 잘못된 경우

.env의 지역과 언어를 확인하세요. 예:

STEAM_STORE_COUNTRY=cn
STEAM_STORE_LANGUAGE=schinese

다음으로 변경할 수도 있습니다:

us
jp
...

수정 후 서비스를 재시작하세요. 프로젝트는 자동 환율 변환을 수행하지 않습니다.

보안

• .env를 커밋하지 않음

• Steam API Key를 커밋하지 않음

• Steam 비밀번호를 저장하지 않음

• Steam Guard를 저장하지 않음

• Steam Cookie가 필요 없음

• API Key를 로그에 출력하지 않음

• debug endpoint는 secret을 반환하지 않음

• Steam 개인정보 보호 설정을 우회하지 않음

• 자동 구매, 거래 또는 Steam 계정 수정을 수행하지 않음

• 기본적으로 127.0.0.1에만 바인딩

공개 네트워크에 배포하는 경우 다음을 추가로 구성해야 합니다:

• HTTPS

• Bearer / OAuth / reverse proxy authentication

• 합리적인 요청 제한

• 로그 마스킹

테스트

테스트는 mock clients 또는 httpx.MockTransport를 사용하여 실제 Steam 상태에 의존하지 않아야 합니다.

실행:

pytest

Mock MCP 스모크 테스트:

python server.py --mock

Invoke-WebRequest http://127.0.0.1:8789/health
Invoke-WebRequest http://127.0.0.1:8789/debug/status

이 프로젝트는 ChatGPT와 Codex의 도움으로 완성되었습니다.