mcp-ps-store

MCP 服务器，用于暴露 PlayStation Network 账户自身的游戏历史——游戏时长、奖杯进度、购买的库——以便 AI 助手能够基于真实数据而非猜测推荐游戏。

俄语版本：README.ru.md。

关于

PSN 没有公开的 API。该服务器与 PlayStation 手机应用使用的内部 API 通信，使用从浏览器会话获取的 NPSSO cookie 进行身份验证。每次请求都是只读操作；不会向账户写入任何内容。

结构采用分层架构：API 层（MCP 工具）、核心层（服务、存储库、DTO）、依赖注入容器和基础设施层。

核心技术

• 语言： Python 3.11+

• 协议： Model Context Protocol (mcp)

• HTTP 客户端： httpx（异步）

• DI 容器： dependency-injector

• 设置： pydantic-settings

• 依赖管理： Poetry

• 测试： Pytest、pytest-asyncio

Related MCP server: PersonalizationMCP

公开的工具

另外还有一个 recommend_games 提示词——一个现成的"构建我的个人资料并推荐游戏"场景，可接受"短时游戏"或"双人合作"等可选引导。

快速开始

需要 Python 3.11+。

1. 安装

使用 Poetry：

poetry install

或使用普通虚拟环境：

python3.11 -m venv .venv && .venv/bin/pip install -e .

2. 登录 PSN

1. 在浏览器中登录 https://www.playstation.com。

2. 打开 https://ca.account.sony.com/api/v1/ssocookie —— 会返回 {"npsso":"..."}。

3. 复制 64 位字符的 npsso 值，然后运行：

poetry run psn-login PASTE_NPSSO_HERE

令牌会以 0600 权限保存到 ~/.mcp-ps-store/tokens.json。

关于会话有效期。 访问令牌有效期为 1 小时，刷新令牌仅 10 天，但 NPSSO 本身有效期约 2 个月。因此 NPSSO 会与令牌一同存储，当刷新令牌过期时服务器会自动重新验证。实际上一次 psn-login 大约可使用 60 天。

3. 验证是否正常

poetry run psn-doctor

它会输出账户名称、可见游戏数量以及按游戏时长排序的前五款游戏。

连接客户端

Claude Code

claude mcp add ps-store -- /path/to/mcp-ps-store/.venv/bin/python -m app.main

Claude Desktop

在 claude_desktop_config.json 中：

{
  "mcpServers": {
    "ps-store": {
      "command": "/path/to/mcp-ps-store/.venv/bin/python",
      "args": ["-m", "app.main"],
      "cwd": "/path/to/mcp-ps-store"
    }
  }
}

Codex CLI

Codex 通过 stdio 与本地 MCP 服务器通信，因此使用方法相同。可以运行 codex mcp add，或者将其添加到 ~/.codex/config.toml：

[mcp_servers.ps-store]
command = "/path/to/mcp-ps-store/.venv/bin/python"
args = ["-m", "app.main"]
cwd = "/path/to/mcp-ps-store"

在 Codex 会话中使用 /mcp 进行验证。

ChatGPT

ChatGPT 无法启动本地进程。自定义连接器需在开发者模式（设置 → 应用 → 高级）中添加，且必须是支持 SSE 或 Streamable HTTP 的公共 HTTPS 端点。因此需要将服务器切换为 HTTP 传输并发布：

PSN_MCP_TRANSPORT=streamable-http PSN_MCP_PORT=8000 poetry run mcp-ps-store

然后通过 HTTPS 暴露 http://127.0.0.1:8000/mcp —— 使用 OpenAI 的 Secure MCP Tunnel，或 cloudflared / ngrok 等隧道工具 —— 并将生成的 URL 添加为自定义连接器。

这会将你的 PSN 历史暴露给所有找到该 URL 的人。 服务器本身没有身份验证，因此请为隧道设置认证，仅在需要时保持运行，如果本地客户端可用，请优先使用 Codex CLI。

配置

所有设置均从环境变量或 .env 文件中读取（参见 .env.example）。

局限性

• 游戏时长仅存在于 PS4 / PS5 / PC 版本。 PSN 对 PS3 和 Vita 游戏仅报告奖杯信息，因此这些游戏会显示 hours: null。

• 此处不包含 PS Store 目录。 商店完全在客户端侧，其 GraphQL API 仅接受每次部署时索尼都会更换哈希值的持久化查询——保持其正常工作不切实际。推荐候选游戏来自模型自身的游戏知识，而 psn_owned_games 可防止推荐已购买的内容。

• 已购买的库 通过 PSN 的私有 GraphQL API 获取。如果索尼更改查询方式，该工具将停止工作；其他所有功能仍正常运行，摘要中会添加 backlog_unavailable 注释。

• 游戏时长和奖杯通过标题关联，因此当重制版与原版共享奖杯集时，两者可能合并。版本、平台后缀和罗马数字会被有意标准化——Alan Wake II 和 Alan Wake 2 被视为同一款游戏。

• 该 API 是非官方的：索尼随时可能更改。

项目结构

.
├── app/
│   ├── api/              # MCP layer: tools, prompts, serialisers, tool errors
│   │   ├── games/
│   │   ├── profile/
│   │   └── taste/
│   ├── core/             # Business logic: services, repositories, DTOs
│   │   ├── auth/         # NPSSO -> tokens, refresh, re-login
│   │   ├── games/        # Library, playtime/trophy merge, name normalisation
│   │   ├── profile/      # Account profile and trophy summary
│   │   └── taste/        # Taste digest aggregation
│   ├── di/               # DI containers and providers
│   ├── infra/adapters/   # HTTP client, token storage, TTL cache
│   ├── cli.py            # psn-login, psn-doctor
│   └── main.py           # MCP server entry point
├── settings/             # pydantic-settings configuration
├── tests/
│   ├── core/             # Merge and aggregation tests
│   └── factories/        # Builders for test data
└── pyproject.toml

开发

poetry run pytest        # unit tests; no network and no account needed
poetry run psn-doctor    # live check against the signed-in account