You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 839d04b
Browse filesBrowse the repository at this point in the historyBrowse files
- 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>
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,6 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
33
33
34
34
### Changed
35
35
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)
36
37
- Large outputs are capped by default to save agent context (#35):
37
38
-`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`.
38
39
-`steam_getOwnedGames` returns `game_count`, `total_playtime_minutes`, and the top 50 games by playtime. New `sort` (`playtime`, `recent`, `name`), `limit`, and `appids` inputs.
Copy file name to clipboardExpand all lines: README.md
+55-50Lines changed: 55 additions & 50 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,82 +31,87 @@ Query Steam store data, player statistics, achievements, reviews, pricing, works
31
31
32
32
> **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.
33
33
34
-
## Getting Started
34
+
## Quick start
35
35
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.
Then ask: *"How many people are playing Team Fortress 2 right now?"* The agent calls `steam_getPlayerCount`, which works even without a key.
51
51
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
53
53
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.
55
55
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).
59
57
60
-
# PowerShell
61
-
$env:STEAM_API_KEY = "your_key_here"
62
-
```
58
+
**Claude Code:**
63
59
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
68
62
```
69
63
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:
77
65
78
66
```json
79
67
{
80
-
"mcpServers": {
68
+
"servers": {
81
69
"steam": {
70
+
"type": "stdio",
82
71
"command": "npx",
83
72
"args": ["-y", "@tmhs/steam-mcp"],
84
-
"env": {
85
-
"STEAM_API_KEY": "your_key_here"
86
-
}
73
+
"env": { "STEAM_API_KEY": "your_key_here" }
87
74
}
88
75
}
89
76
}
90
77
```
91
78
92
-
**Via local clone:**
79
+
**Windsurf:** put the Quick start JSON in `~/.codeium/windsurf/mcp_config.json`.
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
109
104
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). |
110
115
## Debugging
111
116
112
117
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