Steam MCP Server

Overview Schema Source Related Servers Discussions Admin

Get a player's achievements

get_player_achievements

Read-only

Fetch a player's achievement progress for a game via SteamID64 and appid, showing unlocked count, completion percentage, and per-achievement unlock dates.

Instructions

Get a player's achievement progress for one game (unlocked count, % complete, per-achievement unlock dates) by SteamID64 + appid — unlocked/completion_pct always reflect the full list, but the per-achievement achievements array is capped at 200, unlocked first (check returned vs total — most games have far fewer). For the game's full achievement list (names, descriptions, global rarity) independent of any player, use get_game_achievements instead; for just the rarity without a key, use get_global_achievements. Requires STEAM_API_KEY and a public profile with game-details visibility — otherwise it returns found:false — which is also what an appid with no achievements, or no such appid at all, returns; the three are not reported separately, so confirm the appid with get_game.

Input Schema

Name	Required	Description
`appid`	Yes	Steam application id (appid). Get it from search_games.
`steamid`	No	17-digit SteamID64. Omit to use the STEAM_ID configured on the server. Convert a vanity/custom URL name with resolve_vanity_url first.
`language`	No	Language for achievement names/descriptions; overrides STEAM_LANGUAGE. Use Steam's own language NAME — english, russian, schinese/tchinese — not an ISO code like en/ru/zh. An unrecognized value is never an error: text comes back in English and any `tags` list comes back EMPTY, which reads as 'this game has no tags' rather than as a bad language. (Filtering BY tags is the one loud case — it fails outright.)

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.14.0Sep 27, 2026

changedInput schema / properties / language / description

Previous value: -"Language for achievement names/descriptions; overrides STEAM_LANGUAGE."New value: +"Language for achievement names/descriptions; overrides STEAM_LANGUAGE. Use Steam's own language NAME — english, russian, schinese/tchinese — not an ISO code like en/ru/zh. An unrecognized value is never an error: text comes back in English and any `tags` list comes back EMPTY, which reads as 'this game has no tags' rather than as a bad language. (Filtering BY tags is the one loud case — it fails outright.)"

changedOutput schema / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "found": {
-        "const": false,
-        "type": "boolean"
-      },
-      "reason": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "found",
-      "reason"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "achievements": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "achieved": {
-              "type": "boolean"
-            },
-            "name": {
-              "description": "Display name, falling back to the achievement's internal api name when Valve's schema has no localized title for it.",
-              "type": "string"
-            },
-            "unlocked_at": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            }
-          },
-          "required": [
-            "achieved",
-            "unlocked_at"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "completion_pct": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "found": {
-        "const": true,
-        "type": "boolean"
-      },
-      "game": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "The game's name from Valve's achievement schema — occasionally an internal dev codename rather than the store title (e.g. 'Fiber' for Persona 5 Royal). Treat the appid you passed as the reliable identifier, or get the store title from get_game."
-      },
-      "returned": {
-        "type": "number"
-      },
-      "total": {
-        "type": "number"
-      },
-      "unlocked": {
-        "type": "number"
-      }
-    },
-    "required": [
-      "found",
-      "game",
-      "total",
-      "unlocked",
-      "completion_pct",
-      "returned",
-      "achievements"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "found": {
+        "const": false,
+        "type": "boolean"
+      },
+      "reason": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "found",
+      "reason"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "achievements": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "achieved": {
+              "type": "boolean"
+            },
+            "name": {
+              "description": "Display name, falling back to the achievement's internal api name when Valve's schema has no localized title for it.",
+              "type": "string"
+            },
+            "unlocked_at": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "achieved",
+            "unlocked_at"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "completion_pct": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "found": {
+        "const": true,
+        "type": "boolean"
+      },
+      "game": {
+        "description": "The game's name from Valve's achievement schema — occasionally an internal dev codename rather than the store title (e.g. 'Fiber' for Persona 5 Royal). Treat the appid you passed as the reliable identifier, or get the store title from get_game.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "returned": {
+        "type": "number"
+      },
+      "total": {
+        "type": "number"
+      },
+      "unlocked": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "found",
+      "game",
+      "total",
+      "unlocked",
+      "completion_pct",
+      "returned",
+      "achievements"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedv0.13.1Aug 17, 2026

changedOutput schema / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "found": {
-        "const": false,
-        "type": "boolean"
-      },
-      "reason": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "found",
-      "reason"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "achievements": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "achieved": {
-              "type": "boolean"
-            },
-            "name": {
-              "type": "string"
-            },
-            "unlocked_at": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            }
-          },
-          "required": [
-            "achieved",
-            "unlocked_at"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "completion_pct": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "found": {
-        "const": true,
-        "type": "boolean"
-      },
-      "game": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "returned": {
-        "type": "number"
-      },
-      "total": {
-        "type": "number"
-      },
-      "unlocked": {
-        "type": "number"
-      }
-    },
-    "required": [
-      "found",
-      "game",
-      "total",
-      "unlocked",
-      "completion_pct",
-      "returned",
-      "achievements"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "found": {
+        "const": false,
+        "type": "boolean"
+      },
+      "reason": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "found",
+      "reason"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "achievements": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "achieved": {
+              "type": "boolean"
+            },
+            "name": {
+              "description": "Display name, falling back to the achievement's internal api name when Valve's schema has no localized title for it.",
+              "type": "string"
+            },
+            "unlocked_at": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "achieved",
+            "unlocked_at"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "completion_pct": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "found": {
+        "const": true,
+        "type": "boolean"
+      },
+      "game": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "The game's name from Valve's achievement schema — occasionally an internal dev codename rather than the store title (e.g. 'Fiber' for Persona 5 Royal). Treat the appid you passed as the reliable identifier, or get the store title from get_game."
+      },
+      "returned": {
+        "type": "number"
+      },
+      "total": {
+        "type": "number"
+      },
+      "unlocked": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "found",
+      "game",
+      "total",
+      "unlocked",
+      "completion_pct",
+      "returned",
+      "achievements"
+    ],
+    "type": "object"
+  }
+]

Changed3 schema fields changedv0.12.1Jul 30, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

removedOutput schema / anyOf

Removed value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "found": {
-        "const": false,
-        "type": "boolean"
-      },
-      "reason": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "found",
-      "reason"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "achievements": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "achieved": {
-              "type": "boolean"
-            },
-            "name": {
-              "type": "string"
-            },
-            "unlocked_at": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            }
-          },
-          "required": [
-            "achieved",
-            "unlocked_at"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "completion_pct": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "found": {
-        "const": true,
-        "type": "boolean"
-      },
-      "game": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "returned": {
-        "type": "number"
-      },
-      "total": {
-        "type": "number"
-      },
-      "unlocked": {
-        "type": "number"
-      }
-    },
-    "required": [
-      "found",
-      "game",
-      "total",
-      "unlocked",
-      "completion_pct",
-      "returned",
-      "achievements"
-    ],
-    "type": "object"
-  }
-]

addedOutput schema / oneOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "found": {
+        "const": false,
+        "type": "boolean"
+      },
+      "reason": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "found",
+      "reason"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "achievements": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "achieved": {
+              "type": "boolean"
+            },
+            "name": {
+              "type": "string"
+            },
+            "unlocked_at": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "achieved",
+            "unlocked_at"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "completion_pct": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "found": {
+        "const": true,
+        "type": "boolean"
+      },
+      "game": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "returned": {
+        "type": "number"
+      },
+      "total": {
+        "type": "number"
+      },
+      "unlocked": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "found",
+      "game",
+      "total",
+      "unlocked",
+      "completion_pct",
+      "returned",
+      "achievements"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedv0.10.4Jul 26, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "found": {
-        "const": false,
-        "type": "boolean"
-      },
-      "reason": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "found",
-      "reason"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "achievements": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "achieved": {
-              "type": "boolean"
-            },
-            "name": {
-              "type": "string"
-            },
-            "unlocked_at": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            }
-          },
-          "required": [
-            "achieved",
-            "unlocked_at"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "completion_pct": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "found": {
-        "const": true,
-        "type": "boolean"
-      },
-      "game": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "total": {
-        "type": "number"
-      },
-      "unlocked": {
-        "type": "number"
-      }
-    },
-    "required": [
-      "found",
-      "game",
-      "total",
-      "unlocked",
-      "completion_pct",
-      "achievements"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "found": {
+        "const": false,
+        "type": "boolean"
+      },
+      "reason": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "found",
+      "reason"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "achievements": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "achieved": {
+              "type": "boolean"
+            },
+            "name": {
+              "type": "string"
+            },
+            "unlocked_at": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "achieved",
+            "unlocked_at"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "completion_pct": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "found": {
+        "const": true,
+        "type": "boolean"
+      },
+      "game": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "returned": {
+        "type": "number"
+      },
+      "total": {
+        "type": "number"
+      },
+      "unlocked": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "found",
+      "game",
+      "total",
+      "unlocked",
+      "completion_pct",
+      "returned",
+      "achievements"
+    ],
+    "type": "object"
+  }
+]

Addedv0.10.2Jul 22, 2026
Removedv0.8.0Jul 17, 2026

Changed3 schema fields changedv0.3.0Jun 30, 2026

addedInput schema / properties / language

Added value: +{
+  "description": "Language for achievement names/descriptions; overrides STEAM_LANGUAGE.",
+  "minLength": 2,
+  "type": "string"
+}

changedInput schema / properties / steamid / description

Previous value: -"17-digit SteamID64. Convert a vanity/custom URL name with resolve_vanity_url first."New value: +"17-digit SteamID64. Omit to use the STEAM_ID configured on the server. Convert a vanity/custom URL name with resolve_vanity_url first."

changedInput schema / required

Previous value: -[
-  "steamid",
-  "appid"
-]New value: +[
+  "appid"
+]

First observedv0.1.0Jun 29, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnlyHint annotation by disclosing the 200-item cap on the achievements array with unlocked-first ordering, the need to compare returned vs total, and the ambiguous found:false return for three distinct failure conditions. It also explains the language-parameter edge case (unrecognized value returns English with empty tags). These are non-obvious behaviors that annotations alone do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each dense with essential information: purpose and output cap in the first, sibling routing in the second, prerequisites and failure modes in the third. No filler or repetition; the most actionable information (what the tool does) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with an output schema and read-only annotations, the description covers all operational essentials: requirements, ambiguity handling, result-cap semantics, and alternative routes. It explains the three indistinguishable failure cases and directs the agent to confirm appids with get_game, which is exactly the kind of contextual guidance an agent needs. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter already has a full description (e.g., steamid omission default, language name format). The tool description adds contextual output details but no new parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Get a player's achievement progress for one game') and enumerates the exact outputs (unlocked count, % complete, per-achievement unlock dates). It explicitly names sibling tools get_game_achievements and get_global_achievements and states what each alternative does, so an agent can distinguish them without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit routing: 'For the game's full achievement list... use get_game_achievements instead; for just the rarity without a key, use get_global_achievements.' It also states prerequisites (STEAM_API_KEY, public profile with game-details visibility) and recommends confirming ambiguous appids with get_game. This leaves no ambiguity about when to invoke this tool versus its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.