ShaderToy MCP Server for LLM GLSL Compute Shaders

Overview

The ShaderToy MCP Server for LLM GLSL Compute Shaders provides an MCP (Model Context Protocol) server that bridges large language models and ShaderToy content. It lets LLMs discover, retrieve, and learn from ShaderToy examples, turning those examples into context that helps the model generate complex GLSL compute shaders. The server integrates with the ShaderToy API to fetch shader sources, metadata, and thumbnails, and exposes those capabilities as MCP tools so an LLM can call them during generation.

This project is useful when you want to augment an LLM with domain-specific shader knowledge without embedding a large offline dataset. Instead of embedding many shader examples in the prompt, the LLM can call the MCP server to retrieve relevant examples on demand, inspect source code, and produce higher-quality, context-aware GLSL compute shaders for rendering, simulations, or generative visuals.

Features

• MCP-compliant server exposing shader-related tools for LLMs
• Integration with the ShaderToy API to search and fetch public shaders
• Tool endpoints for search, example retrieval, and code fetch (GLSL snippets)
• On-demand example selection so LLMs get targeted context instead of long prompts
• Option to return shader metadata (author, date, tags) alongside code
• Lightweight and modular: can be deployed locally or in containerized environments

Installation / Configuration

Prerequisites:

• Docker (recommended) or Python 3.8+ / Node.js depending on implementation
• ShaderToy API key (register at https://www.shadertoy.com/ for an API key when required)

Quick-start with Docker:

# Clone the repo
git clone https://github.com/wilsonchenghy/ShaderToy-MCP.git
cd ShaderToy-MCP

# Create .env file with your ShaderToy API key
cat > .env <<EOF
SHADERTOY_API_KEY=your_shadertoy_api_key_here
PORT=8080
EOF

# Build and run with Docker Compose (if provided)
docker-compose up --build -d

Manual setup (Python example):

git clone https://github.com/wilsonchenghy/ShaderToy-MCP.git
cd ShaderToy-MCP
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# create .env or export env vars
export SHADERTOY_API_KEY=your_shadertoy_api_key_here
export PORT=8080

# start server (example using uvicorn)
uvicorn app:app --host 0.0.0.0 --port $PORT --reload

Configuration tips:

• Set SHADERTOY_API_KEY in environment to enable API calls.
• Adjust CACHE_TTL to control how long fetched examples are cached for faster responses.
• If deploying behind a proxy, set the server’s host and port accordingly.

Available Tools / Resources

The MCP server exposes a small set of tool endpoints that an LLM can call. Typical endpoints:

Example search request:

POST /tools/search
Content-Type: application/json

{
  "query": "fluid simulation",
  "limit": 5
}

Example fetch request:

POST /tools/fetch
Content-Type: application/json

{
  "shader_id": "XlsGWN"
}

Resources:

• ShaderToy API docs: https://www.shadertoy.com/api
• MCP spec overview (Model Context Protocol) — use to design tool responses and schemas
• Example prompts and tool call templates included in the repo under /examples

Use Cases

1. LLM-assisted shader authoring

   • Flow: LLM calls /tools/search with “reaction-diffusion” → server returns several relevant examples → LLM ingests snippets and returns a compute shader implementing reaction-diffusion with adapted inputs and comments.

2. Educational notebooks and tutorials

   • Educator uses the MCP server in a notebook so students can ask an LLM to explain shader patterns, then fetch example shaders to compare implementations and visualize differences.

3. Rapid prototyping for generative visuals

   • Designer wants a stylized noise-based render. LLM calls /tools/examples, gets snippets for different noise functions, synthesizes a new compute shader that composes these functions and returns runnable GLSL.

4. Automated code augmentation and refactoring

   • Use the server to gather multiple canonical patterns (e.g., camera setups, ray-marching loops). An LLM can then produce a unified, optimized compute shader using the examples as references.

5. Dataset curation & augmentation

   • Researchers can programmatically pull a curated subset of ShaderToy examples for model fine-tuning or for building a training dataset of compute-shader idioms.

Getting Started Examples

Search and fetch (curl):

# search
curl -X POST http://localhost:8080/tools/search \
  -H "Content-Type: application/json" \
  -d '{"query":"raymarch sphere","limit":3}'

# fetch
curl -X POST http://localhost:8080/tools/fetch \
  -H "Content-Type: application/json" \
  -d '{"shader_id":"XlsGWN"}'

Example MCP interaction (pseudocode for an LLM tool call):

{
  "tool": "search_shadertoy",
  "input": {"query":"voronoi + flow", "limit":4}
}

This server is designed to be a drop-in MCP backend for LLM systems that need shader context. Check the repository for example integrations, prompt templates, and deployment variants.