steamstats-mcp

steamstats-mcp

0
entertainment_and_media

The SteamStats MCP Server is designed to facilitate interactions between MCP clients and the Steam Web API by providing structured access to game statistics and user data. Built with Python and FastAPI, this server supports JSON-RPC style requests and integrates with various MCP clients like Roo.

SteamStats MCP Server

Warning

Current implementation is not operational!

Overview

This project implements a SteamStats MCP (Model Context Protocol) Server using Python and FastAPI. The server acts as an intermediary between an MCP client (like Roo) and the Steam Web API, providing structured access to various Steam game statistics and user information.

It exposes a single /message endpoint that accepts JSON-RPC style tools/call requests, validates them, interacts with the Steam Web API, and returns formatted results or appropriate error messages.

Technology Stack

  • Language: Python 3.11+
  • Framework: FastAPI
  • Data Validation: Pydantic
  • Web Server: Uvicorn
  • HTTP Client: Requests
  • Package Management: UV

Request Flow

The following diagram illustrates the typical request flow:

sequenceDiagram
    participant Client as MCP Client
    participant Server as SteamStats MCP Server
    participant SteamAPI as Steam Web API

    Client->>Server: POST /message (tools/call, command, args)
    Server->>Server: Validate MCP message format
    alt Invalid Format
        Server-->>Client: Error Response (e.g., Invalid Request)
    else Valid Format
        Server->>Server: Parse command & arguments
        Server->>Server: Validate arguments using Pydantic
        alt Invalid Arguments
            Server-->>Client: Error Response (Validation Error)
        else Valid Arguments
            Server->>SteamAPI: Make API Request(s) (e.g., GET /ISteamUserStats/...)
            SteamAPI-->>Server: API Response (JSON data or error)
            alt Steam API Error
                Server->>Server: Log API Error
                Server-->>Client: Error Response (API Error)
            else Successful API Response
                Server->>Server: Process API data
                Server-->>Client: Success Response (result data)
            end
        end
    end

Setup and Installation

  1. Prerequisites:

    • Python 3.11 or higher.
    • UV package manager installed (pip install uv).

  2. Clone the repository (if you haven't already):

    git clone <repository-url>
cd steamstats_mcp

  3. Create a virtual environment (recommended):

    # Using uv
uv venv
source .venv/bin/activate # On Linux/macOS
# .venv\Scripts\activate # On Windows

# Or using standard venv
# python -m venv .venv
# source .venv/bin/activate # On Linux/macOS
# .venv\Scripts\activate # On Windows

  4. Install dependencies:

    uv pip install -r requirements.txt # Assuming a requirements.txt exists or will be generated from pyproject.toml
# Or directly from pyproject.toml if using uv for management
# uv sync

    (Note: You might need to generate requirements.txt from pyproject.toml using uv pip freeze > requirements.txt if direct uv sync isn't used)

  5. Configure Environment Variables: See the section below.

Configuration (Environment Variables)

The server requires the following environment variables to be set:

  • STEAM_API_KEY (Required): Your Steam Web API key. Obtain one from the Steam Developer website. The server will not function without this key.
  • LOG_LEVEL (Optional): Sets the logging level. Options include DEBUG, INFO, WARNING, ERROR, CRITICAL. Defaults to INFO.
  • HOST (Optional): The host address for the server to bind to. Defaults to 0.0.0.0 (listens on all available network interfaces).
  • PORT (Optional): The port for the server to listen on. Defaults to 8000.

You can set these variables in your shell environment, using a .env file (requires python-dotenv package and code modification to load it), or through your deployment system's configuration.

Example (Linux/macOS):

export STEAM_API_KEY="YOUR_API_KEY_HERE"
export LOG_LEVEL="DEBUG"
export PORT="8080"

Example (Windows CMD):

set STEAM_API_KEY=YOUR_API_KEY_HERE
set LOG_LEVEL=DEBUG
set PORT=8080

Example (Windows PowerShell):

$env:STEAM_API_KEY = "YOUR_API_KEY_HERE"
$env:LOG_LEVEL = "DEBUG"
$env:PORT = "8080"

Running the Server

Once dependencies are installed and environment variables are configured, run the server using Uvicorn:

uvicorn main:app --host $HOST --port $PORT --reload
  • Replace main:app if your FastAPI application instance is named differently or located in a different file.
  • The --reload flag enables auto-reloading during development (remove for production).
  • Uvicorn will use the HOST and PORT environment variables if set, or their defaults (0.0.0.0 and 8000).

The server should now be running and listening for MCP requests on http://<HOST>:<PORT>/message.

Available MCP Commands

Refer to STEAMSTATS_MCP_SPECIFICATION.md for detailed information on available commands, their arguments, and expected results. Currently implemented commands include:

  • getCurrentPlayers
  • getAppDetails
  • getGameSchema
  • getGameNews
  • getPlayerAchievements
  • getUserStatsForGame
  • getGlobalStatsForGame
  • getSupportedApiList
  • getAppList
  • getGlobalAchievementPercentages

Connecting a Local MCP Client (e.g., Roo)

To connect a local MCP client, such as the Roo VS Code extension, to this running server, you need to configure the client's mcp.json file. This file typically resides in a .roo directory within your project or user settings.

The configuration tells the client how to communicate with the server. Since this is an HTTP-based server (FastAPI/Uvicorn), you'll use the sse (Server-Sent Events) type.

  1. Ensure the SteamStats MCP Server is running: Follow the "Running the Server" instructions above. By default, it runs on http://localhost:8000.
  2. Locate or create your mcp.json file: This might be in .roo/mcp.json in your workspace or a global configuration location.
  3. Add the server configuration: Add an entry to the servers array in mcp.json.

Example mcp.json entry:

{
  "servers": [
    // ... other server configurations ...
    {
      "name": "steamstats-local", // Choose a descriptive name
      "type": "sse",
      "enabled": true,
      "url": "http://localhost:8000/message", // Adjust host/port if you changed defaults
      "readTimeoutSeconds": 60,
      "writeTimeoutSeconds": 60
    }
  ]
}
  • name: A unique identifier for this server connection.
  • type: Must be sse for HTTP-based servers.
  • enabled: Set to true to activate the connection.
  • url: The full URL to the /message endpoint of the running server. Make sure the host and port match how you are running the server (e.g., if you used export PORT=8081, change the URL accordingly).
  • readTimeoutSeconds / writeTimeoutSeconds: Optional timeouts.

Once configured and the server is running, your MCP client should be able to connect and utilize the tools provided by this SteamStats server.