roblox-assets-mcp

About

TL;DR: a local, asset-only MCP server for Roblox Creator Store. An assistant can search reusable assets, inspect their metadata and 2D thumbnails, and request a temporary download URL. It leaves downloading and working with the asset to the assistant's own environment.

Related MCP server: robloxstudio-mcp

Why it exists

I am building a Roblox game with friends and an AI agent. The agent can help with code, but it also needs the same raw material a human creator would look for: models, audio, decals, plugins, and other things already made for Roblox. This server gives it a small set of tools for that part of the work.

For example, I can ask the agent to find a free forest cabin, check who made it and whether it contains scripts, inspect its preview, and get a URL for the asset it chooses. The agent can then fetch and examine the file in its own workspace before using it in a project.

How it works

The assistant calls three tools over local stdio. The server sends HTTPS requests to Roblox with HTTPX, using an Open Cloud API key for Creator Store and Asset Delivery. It reads 2D previews from the public Thumbnails API. The API key stays in the server process and is never part of a tool response.

Philosophy

Only the asset workflow. The three tools follow the path from a search to an inspected asset to a URL that the agent can fetch. Universe and place management belong to a different set of tools.

Let the assistant choose. Search returns structured names, creators, prices and IDs. Details add a preview and script flag when Roblox provides them. The agent has enough information to compare candidates before downloading one.

Keep the key local. Roblox authentication happens in the MCP process. The agent sees asset data and temporary URLs, while the key remains in the process environment. Access is checked before the server announces itself to the client.

Leave files with the caller. The server obtains the CDN location; the assistant decides where to fetch, inspect and store the asset. This keeps filesystem access and game integration in the environment that already owns the project.

What it can do

The search tool accepts these asset types:

Search starts with free models. The assistant can choose another type, include paid results, and request more pages. Thumbnail images may still be pending, and download URLs expire. The server returns the URL; the assistant fetches the file in its own workspace.

Getting an API key

Create a Roblox Open Cloud API key with both scopes below. On startup, the server checks Creator Store and Asset Delivery access and exits if the API key is missing, invalid, or lacks the required scopes. Later authorization or rate-limit failures appear as tool errors.

If you enable IP restrictions, allow the address of the machine running the MCP server. The public 2D thumbnail endpoint needs no additional scope. Keep the key in your MCP client's environment configuration, never in a project file that you commit. A key used only for testing can be revoked afterward.

Installation

Roblox Assets MCP is published on PyPI and runs locally over stdio. Choose your client below and replace YOUR_ROBLOX_OPEN_CLOUD_API_KEY with your key.

Add a server to your Hermes profile's mcp_servers configuration. Pepper's existing profiles use this uvx pattern:

mcp_servers:
  roblox-assets:
    command: uvx
    args: [roblox-assets-mcp]
    env:
      ROBLOX_API_KEY: "${ROBLOX_API_KEY}"

Set ROBLOX_API_KEY in the environment that starts Hermes. See Pepper's configuration for the wider setup.

Run this in a terminal. The user scope makes the server available across projects:

claude mcp add --transport stdio --scope user \
  --env "ROBLOX_API_KEY=YOUR_ROBLOX_OPEN_CLOUD_API_KEY" \
  roblox-assets -- uvx roblox-assets-mcp

Check the connection with claude mcp get roblox-assets or /mcp inside Claude Code. See the Claude Code MCP guide.

Open Settings → Developer → Edit Config and add this entry inside mcpServers:

{
  "mcpServers": {
    "roblox-assets": {
      "command": "uvx",
      "args": ["roblox-assets-mcp"],
      "env": {
        "ROBLOX_API_KEY": "YOUR_ROBLOX_OPEN_CLOUD_API_KEY"
      }
    }
  }
}

Restart Claude Desktop after saving. See Claude Desktop local MCP setup.

Add this to ~/.codex/config.toml. The same user config is used by Codex CLI and its IDE integrations:

[mcp_servers.roblox-assets]
command = "uvx"
args = ["roblox-assets-mcp"]
env = { ROBLOX_API_KEY = "YOUR_ROBLOX_OPEN_CLOUD_API_KEY" }

Restart Codex, then check the server with codex mcp list. See the Codex configuration reference.

Add this server under mcp in your user ~/.config/opencode/opencode.json or project opencode.json:

{
  "mcp": {
    "roblox-assets": {
      "type": "local",
      "command": ["uvx", "roblox-assets-mcp"],
      "environment": {
        "ROBLOX_API_KEY": "YOUR_ROBLOX_OPEN_CLOUD_API_KEY"
      },
      "enabled": true
    }
  }
}

See the OpenCode MCP server guide.

Run:

gemini mcp add --scope user \
  --env "ROBLOX_API_KEY=YOUR_ROBLOX_OPEN_CLOUD_API_KEY" \
  roblox-assets uvx roblox-assets-mcp

Check with gemini mcp list. See the Gemini CLI MCP guide.

Add this to ~/.grok/config.toml:

[mcp_servers.roblox-assets]
command = "uvx"
args = ["roblox-assets-mcp"]
env = { ROBLOX_API_KEY = "YOUR_ROBLOX_OPEN_CLOUD_API_KEY" }
enabled = true

Reload the MCP list in Grok Build after saving. See the Grok Build MCP guide.

Add this MCP client entry to your DeepSeek Harness Cordis profile. Start the harness with ROBLOX_API_KEY set in its environment:

- id: mcp-roblox-assets
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: roblox-assets
    transport: stdio
    command: uvx
    args: [roblox-assets-mcp]
    env:
      ROBLOX_API_KEY: !!js process.env.ROBLOX_API_KEY

See the DeepSeek Harness MCP client guide.

Add this entry under mcpServers in .cursor/mcp.json:

{
  "mcpServers": {
    "roblox-assets": {
      "command": "uvx",
      "args": ["roblox-assets-mcp"],
      "env": {
        "ROBLOX_API_KEY": "YOUR_ROBLOX_OPEN_CLOUD_API_KEY"
      }
    }
  }
}

See the Cursor MCP guide.

Create or edit .vscode/mcp.json:

{
  "servers": {
    "roblox-assets": {
      "type": "stdio",
      "command": "uvx",
      "args": ["roblox-assets-mcp"],
      "env": {
        "ROBLOX_API_KEY": "YOUR_ROBLOX_OPEN_CLOUD_API_KEY"
      }
    }
  }
}

Start the server from the MCP Servers view in Copilot Chat. See VS Code MCP setup.

Add this entry under context_servers in Zed's settings.json:

{
  "context_servers": {
    "roblox-assets": {
      "command": "uvx",
      "args": ["roblox-assets-mcp"],
      "env": {
        "ROBLOX_API_KEY": "YOUR_ROBLOX_OPEN_CLOUD_API_KEY"
      }
    }
  }
}

See the Zed MCP guide.

In either extension's MCP settings, add a local stdio server with command uvx, argument roblox-assets-mcp, and environment variable ROBLOX_API_KEY. Both provide an MCP settings editor in the extension UI. See the Cline MCP guide and Roo Code MCP guide.

Create .continue/mcpServers/roblox-assets.yaml:

name: Roblox Assets MCP
version: 1.0.0
schema: v1
mcpServers:
  - name: Roblox Assets
    command: uvx
    args:
      - roblox-assets-mcp
    env:
      ROBLOX_API_KEY: YOUR_ROBLOX_OPEN_CLOUD_API_KEY

See the Continue MCP guide.

These web apps connect to remote MCP servers. This package runs locally over stdio and does not publish a remote endpoint, so you cannot paste uvx roblox-assets-mcp into their connector settings. Connecting a web app requires a separately hosted or securely tunneled remote MCP endpoint. See Claude remote connectors and ChatGPT MCP connectors.

Technologies

What's inside

.
├── .github/
│   └── workflows/
│       ├── quality.yml        # formatting, lint, tests and build checks
│       └── release.yml        # build and publish a GitHub Release to PyPI
│
├── assets/                  # editable Excalidraw flow and its SVG for this README
│
├── src/roblox_assets_mcp/
│   ├── app.py               # stdio server, tools and startup check
│   ├── client.py            # Roblox HTTP requests and response parsing
│   ├── config.py            # environment settings and their defaults
│   └── models.py            # typed tool responses and asset categories
│
├── tests/                   # behavior checks for the server
├── Makefile                 # local quality commands
└── pyproject.toml           # package metadata and dependencies

Development

Requirements

• Git to work with the repository.

• uv to install Python and project dependencies.

• GNU Make to run the project commands.

Setup

From the repository root:

# Install the dependencies pinned in uv.lock.
uv sync --locked --group dev

Coding

# Format the Python files after editing them.
make format-apply

# Check Python formatting.
make format-check

# Check Python code with Ruff.
make lint

Testing and building

# Run the server tests.
make test

# Build the source distribution and wheel in dist/.
make build

# Run formatting, lint, tests and build together.
make quality

Related projects

• roblox-with-swe is the collaborative Roblox game that motivated this server.

• pepper documents the personal agent that will use it.

Disclaimer

This project is unofficial. It is not made by, affiliated with or endorsed by Roblox.

License

This repository is licensed under the MIT License.

References

• Roblox Creator Store API: search and asset metadata.

• Roblox Asset Delivery API: temporary asset download locations.

• Roblox Thumbnails API: 2D previews.

• Roblox Open Cloud scopes: the permissions used by the API key.

• Model Context Protocol: the tool protocol this server speaks.