mascotforge
Give your AI agent an animated face. Describe a mascot, get a web component with idle, thinking, talking and error states. Blob and 3D styles are free; video uses your own fal key. CLI and MCP server for agents.
Install / Use
claude mcp add Arivex-ca -- npx -y github:Arivex-ca/mascotforgeIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of mascotforge
mascotforge scores 83/100 on our quality scale, 2991st of 4,705 Development & Engineering skills we index.
Its MCP Server is 24 KB long, well organised into 23 sections with 13 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated today, so mascotforge is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
ReviewOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review judged it risky: The README instructs users to disable MCP tool approval for Codex exec by setting `default_tools_approval_mode = "approve"` and running `codex exec -c 'approval_policy="never"'`, which weakens agent safeguards.
AI review: risky
- The README instructs users to disable MCP tool approval for Codex exec by setting `default_tools_approval_mode = "approve"` and running `codex exec -c 'approval_policy="never"'`, which weakens agent safeguards.
- It is otherwise a standard project README documenting installation, API, and usage with no malicious commands or data exfiltration.
- The install/run commands are user-facing documentation, not autonomous agent instructions.
AI review by kimi-k2.7-code on 2026-11-16. Automated pattern scan on 2026-11-16. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
mascotforge compared with similar skills
All 4 of these similar skills score higher than mascotforge; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| mascotforge (this skill)by Arivex-ca | 83 | 3 | today | MCP Server |
| taste-skillby Leonxlnx | 100 | 117.0k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.4k | 9d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install mascotforge?
- Run
claude mcp add Arivex-ca -- npx -y github:Arivex-ca/mascotforge. The install tabs above show the steps for each supported agent. - Which AI agents does mascotforge work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is mascotforge safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review judged it risky: The README instructs users to disable MCP tool approval for Codex exec by setting
default_tools_approval_mode = "approve"and runningcodex exec -c 'approval_policy="never"', which weakens agent safeguards. It is MIT-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand. - Is mascotforge still maintained?
- The repository was last updated today, so mascotforge is actively maintained.
Skill content
View source on GitHubUse it for
- A face for your chat assistant, with listening, thinking, and talking states.
- A status indicator for a coding agent, from active work to an error or completed task.
- Visible progress for background tasks, so users know the process is alive.
- A responsive face for a voice agent, with state changes that need no mouth animation.
The first 10 mascots are on me. Tell me what your agent does and I'll make yours by hand, free. In return, three questions: would you install it, which states are missing, and what does your agent run on?
The studio, CLI help, and API errors are in French for now. Issues and pull requests in English are welcome: see CONTRIBUTING.md.
Gallery
MascotForge produced everything shown below.
AI video: a plush fox, built from one image that Claude Code generated, animated by Kling in four states: idle, thinking, talking, and error. The green background is removed and the loops are seamless. The preview places it on a cream background. Cost: $1.01 for four states.

Cursor tracking, shown here with the Arivex robot: an 8-second clip in which only the head looks in four directions. While idle, the widget displays the frame that looks toward the mouse.

Code mascots: four Blob Atelier blobs and four Wobnimo characters, configured in the studio, each in a different state. They are free, animate in the browser, and follow the cursor.

Drawn by an agent: Codex designed this fox on its own over MCP, with no API key. After the first preview it decided the shape looked like a cat, then fixed it.

Base image generated by the agent: no image to start from and no fal key? Claude Code generated these four plush characters itself, with the free Z-Image Turbo model through its Hugging Face connector, following the MascotForge skill. The chosen image then goes to the video, image-to-3D, or Wobnimo path.

3D character from an image: the source image on the left, followed by two Wobnimo characters written by a model from that image: Visor, then Glimmer with visual comparison. The result is an interpretation in Wobnimo's style, not a copy. It costs about $0.13 to $0.40 per character.

The same character in ten moods from four angles:

The studio






Pipeline:
- Character: upload an image, preferably a cut-out PNG, or enter a text prompt. Flux generates the character on a solid green background. Uploaded images are placed on the same green.
- States on demand: start from a preset for AI agents, websites, or the full set, then add, remove, or freely describe up to 12 states. Each state is a 3-second clip that loops or plays once.
- Kling 3.0 image-to-video generates one clip per state. Each clip starts and
ends on the source image through
end_image_url. Loops stay seamless, and the widget switches states on the shared pose. Audio is disabled. - ffmpeg keying removes the green. Each clip becomes a 480 px stacked-alpha video with color on top and the mask below.
- The
<mascot-avatar>widget rebuilds transparency in WebGL across browsers, including Safari and iOS. - Export produces an importable folder and a zip archive.
Requirements
- Python 3.10 or newer
- ffmpeg and ffprobe on the PATH, or
MASCOTFORGE_FFMPEG. Generation still works without them, but mascots keep their green background.GET /api/healthreports their availability. - For AI video only, a fal.ai key entered in the studio Settings. Blob and
3D mascots need no key.
FAL_KEYremains a useful fallback for a local server. Without an available key, generation routes return503with a clear message.
Installation
git clone https://github.com/Arivex-ca/mascotforge.git
cd mascotforge
python -m venv .venv
.venv/bin/pip install -r requirements.txt # Windows: .venv\Scripts\pip
cp .env.example .env # then set FAL_KEY
Run
.venv/bin/python -m uvicorn backend.main:app --port 8766 --env-file .env
--env-file loads FAL_KEY and local settings from .env. User-owned keys
arrive through dedicated headers.
- Studio:
http://localhost:8766/ - Widget and demo:
http://localhost:8766/widget/
Key settings and security
The studio Settings button accepts a fal.ai key and an optional OpenRouter key.
Without "Remember on this device," the studio uses sessionStorage. With the
option enabled, it uses localStorage. All access to these stores falls back
to memory if the browser blocks them.
The browser sends the required key in an X-Fal-Key or X-OpenRouter-Key
header only when an operation needs it. The 3D image reader provider travels in
X-Vision-Provider: fal|openrouter. Keys never enter a URL or query parameter.
The server keeps a key in the request and task context. It does not write keys
to jobs, data/, logs, or responses.
FAL_KEY is the local fallback when X-Fal-Key is missing. GET /api/health
therefore continues to report only the server key. The studio displays the
state of the browser key separately.
Do not set FAL_KEY on a server that other people can reach: every visitor
without a key would generate videos on your fal account. The monthly cap
(MASCOTFORGE_MONTHLY_CAP_USD) is also shared by everyone using the server.
The Test button starts no generation. OpenRouter checks the key with
GET https://openrouter.ai/api/v1/key. fal.ai uses the fal-client storage
token request without uploading a file or running inference.
For agents
The CLI and MCP server use the existing API. Configure the server address with
MASCOTFORGE_URL, which defaults to http://localhost:8766. To provide keys
without placing them in a URL or output, use MASCOTFORGE_FAL_KEY and
MASCOTFORGE_OPENROUTER_KEY. The client sends them through the two dedicated
headers.
CLI
python -m mascotforge styles
python -m mascotforge code --engine blob --set shape=cloud --out ./mon-blob
python -m mascotforge code --engine 3d --set character=volt --out ./mon-robot
python -m mascotforge blob guide --out ./guide-blob.md
python -m mascotforge blob check ./blob.json
python -m mascotforge blob preview ./blob.json --out ./planche-blob.png
python -m mascotforge blob export ./blob.json --out ./blob-sur-mesure
python -m mascotforge image3d ./robot.png --out ./robot-3d
python -m mascotforge video --image ./robot.png --usage agent --out ./robot-video
python -m mascotforge video --prompt "un petit renard orange" --usage site --out ./renard
python -m mascotforge video --image ./renard.png --states ./etats.json --out ./renard
python -m mascotforge status ID
python -m mascotforge export ID --out ./export
python -m mascotforge cost
Free loop: the agent draws the mascot itself
For a blob outside the eight built-in shapes, the agent describes a
superellipse and its bumps in a JSON spec. blob check rejects intersections,
outlines that are too thin, too small, or too large, and out-of-range values.
blob preview displays all eight states before the standalone export. The
guide includes a two-horned blob, a star, and a twisted bean.


python -m mascotforge blob guide --out ./guide-blob.md
python -m mascotforge blob check ./blob.json
python -m mascotforge blob preview ./blob.json --out ./planche-blob.png
python -m mascotforge blob export ./blob.json --out ./blob-sur-mesure
An agent that can see an image can write the Wobnimo spec directly, without a fal.ai call or cost. The server retains the checker, renderer, Node runtime, and storage. The loop is visual:
- Inspect the reference image and read the guide.
- Write the JSON spec, then run the check.
- Generate the sheet and compare its front view in the top-left corner with the source image.
- Correct the spec, then repeat the check and preview.
- Save the spec or export it when the result is accurate.
python -m mascotforge spec guide --out ./guide-wobnimo.md
python -m mascotforge spec check ./personnage.json
python -m mascotforge spec preview ./personnage.json --out ./planche.png
python -m mascotforge spec save ./personnage.json
python -m mascotforge spec export ./personnage.json --out ./personnage-3d
These commands are free and do not require --yes. The image3d command is
the paid option where a fal.ai model writes the spec.
Add --json to a command for agent-readable output. The image3d and video
commands are paid. Without --yes, they display the estimated price and exit
with a non-zero status before starting. Run the command again with --yes
only after the user agrees.
MCP over stdio
python -m mascotforge mcp
Long-running creations use three calls: mascotforge_video_start or
mascotforge_image3d_start, followed by mascotforge_status, then
mascotforge_export. Paid start tools require user_confirmed=true. Their
descriptions require the agent to state the price and obtain explicit consent.
The free mascotforge_spec_guide, mascotforge_spec_check,
mascotforge_spec_preview, mascotforge_spec_save, and
mascotforge_spec_export tools follow the same loop. The preview returns as an
MCP image so the agent can inspect the sheet, compare it with the reference,
and correct the spec before saving it.
The four custom Blob tools are mascotforge_blob_guide,
mascotforge_blob_check, mascotforge_blob_preview, and
mascotforge_blob_export. Their preview also returns as an MCP image.
Claude Desktop configuration in %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"mascotforge": {
"command": "C:\\pa
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
117.0kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.4kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
