Skip to content

Commit 839d04b

Browse files
TMHSDigitalclaude
andcommitted
docs(readme): npx quick start, per-client setup, troubleshooting
- One-snippet quick start; Cursor, Claude Desktop, Claude Code, VS Code, Windsurf configs; local clone moved to a collapsed section - API key section says env block only; removed .env instructions (the server never loaded .env) - Troubleshooting table for missing/invalid keys, publisher 403s, private profiles, hidden mutation tools, npx cache, Windows spawning Fixes #39 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 07b627f commit 839d04b

2 files changed

Lines changed: 56 additions & 50 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
3333

3434
### Changed
3535

36+
- README onboarding starts with a one-snippet npx quick start and adds setup for Claude Desktop, Claude Code, VS Code, and Windsurf, plus a troubleshooting table. Removed the `.env` instructions: the server never loaded `.env`. (#39)
3637
- Large outputs are capped by default to save agent context (#35):
3738
- `steam_getAppDetails` returns a compact summary (about 2 KB instead of about 30 KB). `detail: "full"` returns every field, `fields` picks specific ones. Store HTML is stripped and long text truncated unless `include_html: true`.
3839
- `steam_getOwnedGames` returns `game_count`, `total_playtime_minutes`, and the top 50 games by playtime. New `sort` (`playtime`, `recent`, `name`), `limit`, and `appids` inputs.

‎README.md‎

Lines changed: 55 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -31,82 +31,87 @@ Query Steam store data, player statistics, achievements, reviews, pricing, works
3131

3232
> **No API key required** for most features. Store lookups, player counts, global achievement stats, news, reviews, and app searches all work out of the box.
3333
34-
## Getting Started
34+
## Quick start
3535

36-
### Prerequisites
36+
Requires Node.js 22 or later. No clone or build needed: add this to your MCP client's config and restart it.
3737

38-
- Node.js 22 or later
39-
- npm
40-
41-
### Install
42-
43-
```bash
44-
git clone https://github.com/TMHSDigital/Steam-MCP.git
45-
cd Steam-MCP
46-
npm install
47-
npm run build
38+
```json
39+
{
40+
"mcpServers": {
41+
"steam": {
42+
"command": "npx",
43+
"args": ["-y", "@tmhs/steam-mcp"],
44+
"env": { "STEAM_API_KEY": "your_key_here" }
45+
}
46+
}
47+
}
4848
```
4949

50-
### Steam API Key
50+
Then ask: *"How many people are playing Team Fortress 2 right now?"* The agent calls `steam_getPlayerCount`, which works even without a key.
5151

52-
Some tools require a Steam Web API key. Get one free at [steamcommunity.com/dev/apikey](https://steamcommunity.com/dev/apikey).
52+
## Client setup
5353

54-
Set it as an environment variable:
54+
**Cursor:** put the Quick start JSON in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global). Pair it with the [Steam Developer Tools](https://github.com/TMHSDigital/Steam-Cursor-Plugin) plugin for 30 skills that use these tools.
5555

56-
```bash
57-
# Bash / macOS / Linux
58-
export STEAM_API_KEY="your_key_here"
56+
**Claude Desktop:** put the Quick start JSON in `claude_desktop_config.json` (Settings > Developer > Edit Config).
5957

60-
# PowerShell
61-
$env:STEAM_API_KEY = "your_key_here"
62-
```
58+
**Claude Code:**
6359

64-
Or in a `.env` file:
65-
66-
```
67-
STEAM_API_KEY=your_key_here
60+
```bash
61+
claude mcp add steam -e STEAM_API_KEY=your_key_here -- npx -y @tmhs/steam-mcp
6862
```
6963

70-
Tools that don't need a key work out of the box with zero configuration.
71-
72-
## Usage with Cursor
73-
74-
Add the Steam MCP server to your Cursor MCP settings (`.cursor/mcp.json` in your project or global settings):
75-
76-
**Via npx (recommended):**
64+
**VS Code (Copilot agent mode):** `.vscode/mcp.json` uses a `servers` key:
7765

7866
```json
7967
{
80-
"mcpServers": {
68+
"servers": {
8169
"steam": {
70+
"type": "stdio",
8271
"command": "npx",
8372
"args": ["-y", "@tmhs/steam-mcp"],
84-
"env": {
85-
"STEAM_API_KEY": "your_key_here"
86-
}
73+
"env": { "STEAM_API_KEY": "your_key_here" }
8774
}
8875
}
8976
}
9077
```
9178

92-
**Via local clone:**
79+
**Windsurf:** put the Quick start JSON in `~/.codeium/windsurf/mcp_config.json`.
9380

94-
```json
95-
{
96-
"mcpServers": {
97-
"steam": {
98-
"command": "node",
99-
"args": ["/absolute/path/to/Steam-MCP/dist/index.js"],
100-
"env": {
101-
"STEAM_API_KEY": "your_key_here"
102-
}
103-
}
104-
}
105-
}
81+
**Any other MCP client:** run `npx -y @tmhs/steam-mcp` as a stdio server.
82+
83+
<details>
84+
<summary><strong>Run from a local clone instead</strong></summary>
85+
86+
```bash
87+
git clone https://github.com/TMHSDigital/Steam-MCP.git
88+
cd Steam-MCP
89+
npm install
90+
npm run build
10691
```
10792

108-
Once configured, the tools are available to Cursor's AI agent. Pair with the [Steam Developer Tools](https://github.com/TMHSDigital/Steam-Cursor-Plugin) plugin for the full skill set.
93+
Then use `"command": "node"` and `"args": ["/absolute/path/to/Steam-MCP/dist/index.js"]` in place of the npx command.
94+
95+
</details>
96+
97+
## Steam API key
98+
99+
About half the tools work with no key at all. The rest need a free Steam Web API key from [steamcommunity.com/dev/apikey](https://steamcommunity.com/dev/apikey). Leaderboard and write tools need a **publisher** key from Steamworks, with the server's IP allowlisted.
100+
101+
Set the key in the `env` block of your client config, as in the Quick start. The server reads `STEAM_API_KEY` from its environment only. It does not load a `.env` file.
102+
103+
## Troubleshooting
109104

105+
| Symptom | Cause and fix |
106+
|---------|---------------|
107+
| `STEAM_API_KEY environment variable is not set` | The key is not in the server's `env` block. Shell exports do not reach servers that your client launches. Add it to the client config and restart the client. |
108+
| `Steam rejected STEAM_API_KEY` | The key is wrong or revoked. Check it at steamcommunity.com/dev/apikey. |
109+
| HTTP 401/403 on leaderboard or write tools | These need a Steamworks publisher key for an app you own, and your IP on the key's allowlist. A regular user key gets 403. |
110+
| "profile or game details are private" | The player's Steam privacy settings hide this data. Nothing on your side can change that. |
111+
| A write tool such as `steam_setAchievement` is missing | Live-mutation tools are off by default. Set `"STEAM_MCP_TOOLSETS": "all"` in `env`. |
112+
| Old behavior after an update | `npx` is serving a cached copy. Use `@tmhs/steam-mcp@latest` in `args`, or run `npm cache clean --force`. |
113+
| Server fails to start on Windows | Some clients cannot spawn `npx` directly. Use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@tmhs/steam-mcp"]`. In JSON, write Windows paths with `\\` or `/`. |
114+
| Anything else | Set `"STEAM_MCP_DEBUG": "1"` and check the server's stderr log (see Debugging below). |
110115
## Debugging
111116

112117
Set `STEAM_MCP_DEBUG=1` in the server's `env` block. The server then writes one line per Steam request to stderr (stdout is the MCP channel), and also sends it to clients that show MCP server logs:

0 commit comments

Comments
 (0)