Skip to main content
Glama
Game Asset Finder MCP

Game Asset Finder MCP

by sudoriaa

Game Asset Finder MCP

CI License: MIT

A "search-first" MCP service for game development. It queries multiple public asset sources and an optional local asset library simultaneously, unifies results from different sites into a common set of fields, and performs Chinese keyword expansion, license normalization, relevance sorting, cross-source deduplication, source diversification, caching, and cursor-based pagination.

The project is built on the current MCP TypeScript SDK v2, runs over stdio, and is suitable for Codex, ChatGPT Desktop, and other clients that support local MCP.

Design and Optimizations

The project uses a provider registry and a unified result model, with a focus on optimizing the cross-source search layer:

  • A single source failure does not bring down the entire search; the response explicitly marks the status of each source.

  • Keyword weighting and Chinese/English game term expansion improve recall for Chinese queries.

  • TTL/LRU caching, deduplication of identical concurrent requests, per-provider timeouts, limited retries, and Retry-After support are implemented.

  • Unified license filtering, canonical URL deduplication, merging of mirror sources, stable sorting, and source diversification are included.

  • Pagination uses limit + nextCursor to avoid dumping a large number of results into the model context.

  • Local indexing uses incremental scanning, SHA-256, atomic writes, root directory constraints, and symlink skipping.

  • The tool surface is compressed to 4 tools, reducing the chance of the agent picking the wrong tool.

Related MCP server: @codesift/mcp

Data Sources

id

Content

Credentials

License Characteristics

kenney

2D, 3D, UI, audio, font asset packs

None

CC0

opengameart

2D, 3D, music, sound effects

None

Varies per item

itch

Free game asset listings

None

Varies per author/page

openverse

Images, textures, icon references

None

CC / Public Domain

ambientcg

PBR materials, HDRI, 3D

None

CC0

polyhaven

Textures, HDRI, 3D

None

CC0

freesound

Sound effects, recordings

FREESOUND_API_KEY

Varies per item

local

Local assets in config directory

Local directory

Described by sidecar

Any remote source may be temporarily unavailable or rate-limited. The sourceStatuses in the return value gives ok / partial / disabled / timeout / rate_limited / error for each source; other successful sources still return results.

Installation

Requires Node.js 20.18.1 or higher.

git clone https://github.com/sudoriaa/game-asset-finder-mcp.git
cd game-asset-finder-mcp
npm ci
npm run build
npm test

Alternatively, you can run:

.\install.ps1

Start directly:

node .\dist\index.js

stdio's standard output is the MCP JSON-RPC channel; service logs go only to standard error.

Integration with Codex

Add to ~/.codex/config.toml or a trusted project's .codex/config.toml:

[mcp_servers.game_assets]
command = "node"
args = ["C:\\path\\to\\game-asset-finder-mcp\\dist\\index.js"]
cwd = "C:\\path\\to\\game-asset-finder-mcp"
startup_timeout_sec = 30
tool_timeout_sec = 90
enabled = true

[mcp_servers.game_assets.env]
GAME_ASSET_LOCAL_ROOTS = "D:\\GameAssets;E:\\SharedAssets"
GAME_ASSET_CACHE_TTL_SECONDS = "600"

If Freesound is enabled, it is recommended to forward the key from the local environment rather than writing the value into the configuration:

[mcp_servers.game_assets]
env_vars = ["FREESOUND_API_KEY"]

You can also add a stdio server using the Codex CLI:

codex mcp add game-assets -- node "C:\path\to\game-asset-finder-mcp\dist\index.js"
codex mcp list

After saving the configuration, restart the client and check the connection status with /mcp. The mcp-config.example.toml in the repository can be copied and modified directly.

MCP Tools

search_game_assets

Cross-source search. Main parameters:

{
  "query": "像素风地牢角色",
  "types": ["sprite", "tileset"],
  "sources": ["kenney", "opengameart", "itch"],
  "formats": ["png"],
  "tags": ["retro"],
  "license_policy": "commercial",
  "include_unknown_license": false,
  "limit": 12,
  "refresh": false
}

license_policy can be:

  • any: Show all results, explicitly marking unknown licenses.

  • commercial: Keep only known commercially usable licenses; use include_unknown_license to bring back unknown items.

  • cc0: Keep only CC0 / Public Domain Mark.

  • no-attribution: Keep only items that are known to be commercially usable and do not require attribution.

To get the next page, put the returned nextCursor into cursor unchanged, keeping other query parameters the same. Using an old cursor after modifying query conditions will return CURSOR_QUERY_MISMATCH.

hasMore indicates whether there is a next page in the current cached candidate snapshot, not that all historical results from the remote site have been fetched; for deeper results, prioritize narrowing the keyword, type, or source range and re-search.

get_game_asset

Read the full record of an asset just searched:

{ "asset_id": "kenney:roguelike-characters" }

Returns source, author, license, preview, file variants, mirror sources, match reason, and attribution text that can be directly added to credits. Remote entries are first searched, then read; local entries can also be read directly from the index.

list_asset_sources

List all providers, enabled status, supported asset types, credential requirements, cache configuration, and local index status.

index_local_assets

Scan GAME_ASSET_LOCAL_ROOTS:

{ "mode": "incremental", "max_files": 20000 }

incremental reuses SHA-256 for files whose size and modification time have not changed; rebuild recomputes everything. The index is written to GAME_ASSET_DATA_DIR/local-assets.json and does not modify asset files.

Local Asset Sidecar

Place hero.png.asset.json or hero.asset.json next to hero.png:

{
  "title": "Azure Knight",
  "description": "32x32 pixel hero with idle and run frames",
  "type": "sprite",
  "tags": ["player", "knight", "pixel-art"],
  "author": "Studio Name",
  "author_url": "https://example.com",
  "license": "CC-BY-4.0",
  "license_url": "https://creativecommons.org/licenses/by/4.0/",
  "source_url": "https://example.com/azure-knight"
}

Local files without a sidecar can still be searched, but the license will be shown as unknown.

Environment Variables

Variable

Default

Description

GAME_ASSET_LOCAL_ROOTS

Empty

Local asset root directories; Windows uses ;, macOS/Linux uses :

GAME_ASSET_DATA_DIR

data under project

Local index directory

GAME_ASSET_CACHE_TTL_SECONDS

600

Query cache TTL in seconds

GAME_ASSET_CACHE_MAX_ENTRIES

200

Maximum number of query cache entries

GAME_ASSET_PROVIDER_TIMEOUT_MS

15000

Per-provider timeout

GAME_ASSET_MAX_RESPONSE_BYTES

16777216

Maximum single remote response size

GAME_ASSET_MAX_RETRIES

2

Retry count for 429/temporary errors

GAME_ASSET_MAX_LOCAL_FILES

20000

Default file limit for local index

GAME_ASSET_DISABLED_SOURCES

Empty

Comma-separated provider IDs

FREESOUND_API_KEY

Empty

Optional Freesound API key

Development and Verification

npm run check
npm test
npm run test:unit
npm run test:mcp

Tests cover Chinese query expansion, type recognition, license policy, URL normalization, deduplication, cache-bust merging, partial provider failure, pagination and cursors, local incremental indexing, and tools/list / tools/call with a real stdio MCP client.

Usage Tips for Results

MCP returns asset discovery and license metadata, not a substitute for the final terms on the source page. Unknown licenses are explicitly kept as id: null; before publishing, you can narrow down with commercial, cc0, or no-attribution, and save source and attribution information from get_game_asset.

Available Tools

4 tools
get_game_assetGet game asset detailsA
Read-onlyIdempotent

Read the full normalized record for an asset returned by search_game_assets, including files, license guidance, alternates, and attribution text.

Inputs: asset_id (required).

index_local_assetsIndex local game assetsA
Idempotent

Incrementally scan GAME_ASSET_LOCAL_ROOTS, hash changed files, read optional .asset.json metadata, and atomically refresh the local search index. Symbolic links are skipped.

Inputs: mode, max_files.

list_asset_sourcesList game asset sourcesA
Read-onlyIdempotent

List provider ids, supported asset kinds, enablement state, local index state, and active limits.

Inputs: no named parameters.

search_game_assetsSearch game assetsA
Read-onlyIdempotent

Search enabled remote and local game-asset sources concurrently. Results are normalized, license-filtered, relevance-ranked, de-duplicated, source-diversified, cached, and cursor-paginated.

Inputs: query (required), tags, limit, types, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct purpose: search, get details, list sources, and index. There is no overlap in functionality, making it easy for an agent to select the right tool.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (get_game_asset, list_asset_sources, search_game_assets, index_local_assets). This predictable structure aids agent understanding.

    Tool Count5/5

    Four tools cover the essential operations for a game asset finder: search, get detail, list sources, and index local assets. The count is well-scoped for the server's stated purpose.

    Completeness5/5

    The tools provide a complete workflow: index local assets, search across sources, retrieve detailed records, and list source info. No obvious gaps exist for the domain of finding and retrieving game assets.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A local MCP server for Nexus Mods mod discovery and research, backed by the v2 GraphQL API, enabling search of games, mods, collections, and users.
      82 npm
      1
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that aggregates web search results from multiple engines and optionally renders pages to Markdown, providing a unified search interface.
      6 npm
      3
      ISC