MCPET
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
MCPET
Small paws. Big feelings. A virtual pet that lives in your agent chat.
Adopt any animal, imaginary creature, or hybrid. Feed it, groom it, play together, and win its affection using ordinary conversation. Keep a separate companion per agent, or release one and adopt again. Pet actions return useful text, action-aware ASCII art, structured status, and an original locally rendered PNG portrait when a pet exists. Health, loneliness, personalities, adventures, tricks, supplies, XP, badges, and a tiny diary give those little visits a life of their own. No API keys, image downloads, paid services, or extra model required.


This is a real Streamable HTTP MCP server, not a chat app or custom widget. Your agent host must support HTTP MCP tools. Inline image display depends on that host's handling of native MCP image results; some hosts expose images only to the model, collapse tool results, or show text only. Text meters always accompany the image. This project cannot force a host to display it.
Start in two minutes
Requires Node.js 22.18+ and npm. In PowerShell:
git clone https://github.com/oliverseges/MCPET.git
Set-Location .\MCPET
npm ci
npm run build
npm startAlready cloned or downloaded the project? Change to its directory and start at
npm ci. Keep the process running while chatting.
Endpoint | Purpose |
| Streamable HTTP MCP connection |
| JSON readiness check |
Invoke-RestMethod http://127.0.0.1:3000/healthRelated MCP server: CubeLife
Connect your agent
In your host's MCP server settings, add an HTTP / Streamable HTTP server
named mcpet with URL http://127.0.0.1:3000/mcp. No token or custom headers
are required. Approve only the tools you want the agent to use. This project
does not modify your global agent configuration or register itself.
For VS Code, merge into .vscode/mcp.json:
{
"servers": {
"mcpet": {
"type": "http",
"url": "http://127.0.0.1:3000/mcp"
}
}
}For hosts that use an mcpServers configuration with HTTP transports:
{
"mcpServers": {
"mcpet": {
"type": "http",
"url": "http://127.0.0.1:3000/mcp"
}
}
}Configuration formats differ between hosts; use its HTTP settings if it rejects
this shape. Do not configure this as an SSE-only /sse server or a stdio command.
An HTTP server runs separately; adding the URL does not start Node for you.
Only a host on this computer can reach this loopback address: cloud-hosted agents
cannot connect to your machine's 127.0.0.1.
Then say:
Adopt a bunny named Waffles.
Adopt a dragon-axolotl named Pip, with mint scales, gold wings, and pink gills.
How is my pet? Show its picture and meters.
Feed Waffles, groom them, and play together.
Give Waffles a cuddle and a cozy nap.
Teach Pip to wave, then take them stargazing.
Read my pet's diary. What have we achieved together?
The host discovers the tools and the agent chooses calls from your conversation. No background agent or model runs inside MCPET. Tools act only when called. Choose one adoption example: an existing companion is never replaced.
A pet per agent, and safe goodbyes
Every tool accepts an agent_id. Choose a stable key unique to each
agent/conversation and reuse it on every call, including after reconnecting:
{"agent_id": "research-thread-42", "name": "Pip", "species": "dragon-axolotl"}That is an adopt_pet call. Feed the same pet using:
{"agent_id": "research-thread-42"}Use the same argument for get_pet, play_with_pet, groom_pet, cuddle_pet,
rest_pet, mistreat_pet, and apologize_to_pet. Appearance editing adds its
appearance field alongside agent_id. Valid IDs are 1-64 lowercase letters,
digits, hyphens, or underscores, starting with a letter or digit. Paths are not
accepted or used to select save files.
Different keys mean independent pets, not different HTTP connections. All slots
survive reconnects and server restarts in the same save file. Omitted IDs retain
the shared default slot for compatibility: the existing legacy pet stays
there unchanged. Ask for agent_id: "default" when caring for that companion.
Two agents that omit the ID still share that slot; the server cannot infer their
identities. Hosts do not universally send stable agent identifiers, so the agent
must remember its key in the conversation or host instructions. Losing that
context does not delete the pet, but you need the original key to find it again.
To get rid of a pet, explicitly ask the agent to release it. release_pet
requires confirmation in its arguments:
{"agent_id": "research-thread-42", "confirm": true}It removes only that slot's saved pet, appearance, and care history, depicting
a safe move to the sanctuary. You may then call adopt_pet for that same ID.
Release also works for a runaway pet. Other slots, including default, are not
affected. The tool is marked destructive, is never called as routine care, and
has no undo; missing or false confirmation is rejected.
Agent IDs provide logical isolation, not authentication or access control. A caller that knows another key can explicitly operate that slot. Use separate server instances/data directories if you need different trust boundaries.
Little ASCII moments
Pet actions include a fenced, monospace drawing beside the reaction and meters:
* brush brush * ||||||
(\_/)
(o.o)
(")(")Feeding gets a dinner caption, play a bouncing toy, cuddles hearts, and naps
sleepy eyes and z Z z. Adoption, redraws, apologies, warnings, releases, and
sanctuary stays have their own moments too. Cats, dogs, and bunnies have small
ASCII silhouettes; all other real or invented species use a generic creature.
It is a lightweight text illustration, not an anatomically accurate rendering of
the vector template. No extra model call is made. Even text-only MCP hosts can
read it; whether the agent echoes a tool result into its final reply is up to
that host and agent. Validation errors rejected before a tool runs use the SDK's
ordinary error response instead.
Any creature, drawn by your agent
species is now a free-form, single-line description (1-80 characters), not a
fixed animal list: octopus, moon-moth, cloud dragon, or owl-cat with butterfly wings are all valid. Care mechanics work identically for every creature.
The calling agent can fill in an optional appearance template during adoption,
or call set_pet_appearance to redraw the current companion later. It is a small
vector scene, not a prompt for an image model. MCPET rasterizes those shapes into
the same native PNG tool result as before. No image-generation capability,
external model, API key, raw SVG, or downloaded artwork is needed.
For example, the agent can call adopt_pet with:
{
"name": "Pip",
"agent_id": "research-thread-42",
"species": "mint dragon with golden wings",
"appearance": {
"shapes": [
{"type": "polygon", "points": [{"x": 110, "y": 170}, {"x": 15, "y": 95}, {"x": 35, "y": 235}], "fill": "#edc984"},
{"type": "polygon", "points": [{"x": 210, "y": 170}, {"x": 305, "y": 95}, {"x": 285, "y": 235}], "fill": "#edc984"},
{"type": "ellipse", "cx": 160, "cy": 225, "rx": 65, "ry": 68, "fill": "#94c6b5"},
{"type": "polygon", "points": [{"x": 119, "y": 99}, {"x": 121, "y": 31}, {"x": 151, "y": 88}], "fill": "#edc984"},
{"type": "polygon", "points": [{"x": 169, "y": 88}, {"x": 199, "y": 31}, {"x": 201, "y": 99}], "fill": "#edc984"},
{"type": "ellipse", "cx": 160, "cy": 139, "rx": 79, "ry": 68, "fill": "#a9d8c6"}
],
"face": {"x": 160, "y": 139, "scale": 1}
}
}The template's canvas is 320 x 320. Shapes are drawn in array order, back to front, and clipped to that canvas. There can be 1-64 shapes:
Shape | Required geometry |
|
|
|
|
|
|
|
|
Coordinates are 0-320; positive sizes are at most 320. Filled shapes support
fill, stroke, and strokeWidth (0-8). Paint is a six-digit hex color such as
#94c6b5, or none; default fill is mint, default stroke is none. Lines default
to a brown, 3-pixel stroke and accept a width of 1-8.
The optional face positions the automatically mood-animated eyes, cheeks,
nose, and mouth; leave space in the head for them. Defaults are the example's
center and scale. x may be 60-260, y 60-250, and scale 0.4-1.3.
Set face.visible to false for an eyeless creature or to draw your own face
using shapes. Status meters and mood text still update; a fully custom face's
expression is then up to the drawing rather than automatically animated.
These are stylized vector companions, not photorealistic illustrations or unrestricted generative images. The species name is preserved in text even if the template is only an approximation. Cat, dog, and bunny retain their built-in portraits. Other species without a supplied template get an explicitly labeled generic companion image, which the agent can refine later. Template validation rejects scripts, raw SVG, URLs, extra attributes, and oversized input rather than rendering untrusted markup. The existing 32 KiB request limit still applies.
Existing saves without an appearance keep working. Redrawing a pet changes
only its appearance, not its identity, adoption date, history, or care meters
(normal elapsed-time effects still apply). No pet is reset during this upgrade.
After updating a running server, reconnect/refresh the host's MCP tools so the
agent discovers the new template and set_pet_appearance tool.
The tiny handbook
One pet lives in each stable agent slot. Connected clients using the same
agent_id care for the same pet; adopting twice will not overwrite it.
Ask about your pet and get its full card. get_pet returns the portrait PNG
with all six status meters, matching text stats, mood, and ASCII art, just like
care actions. The server instructs the agent to present the whole card rather
than only a mood summary. This works for arbitrary species and custom drawings.
Native image display still depends on the host; all six stats are included in
text even when a host cannot display the PNG.
Tool | What happens |
| Choose |
| Supply an |
| Explicitly remove the selected slot's pet using |
| Portrait, mood, text meters, warnings, and care advice |
| Hunger -35, happiness +8, love +4; refuses if hunger is below 10 |
| Happiness +22, love +7, energy -20, hunger +10, cleanliness -8; needs 20 energy and hunger below 85 |
| Cleanliness +35, happiness +8, love +5 |
| Love +12, happiness +10 |
| An immediate cozy nap restores 35 energy; does not fast-forward time |
| Explicit fictional teasing/scolding only: happiness -30, love -25, one boundary warning |
| At home: removes one warning, love +3. Away: invites the pet home after an hour |
| Explicit rescue/healing: health +60, hunger at most 35, energy at least 55, happiness at least 40, cleanliness at least 70; clears neglect, preserves identity/history |
| One coherent activity menu: adventure, learn/perform trick, use/buy item, or journal; see below |
All tools accept agent_id (default: default). Care/status tools need no other
arguments; adoption, appearance editing, release, and activities have the fields above. All meters clamp to
0-100. Hunger is better low; every other meter is better high. Illustrations
reflect species, health, mood, low energy, dirt, high affection, and sanctuary stays.
Health, starvation, loneliness, and recovery
Per real hour: hunger +3, happiness -1.5, cleanliness -1, love -0.3, energy +4. A new pet starts with 100 health. While hunger is at 100, starvation removes 6 health per hour. The calculation integrates only time after hunger actually reaches 100: reaching it at the end of an interval does not charge damage for the whole interval. Feeding stops further starvation but does not magically repair damage; visit the vet to heal.
At health 0, the pet explicitly collapses (status: "critical").
The card shows zero health, a first-aid marker, and a rescue instruction.
Ordinary care and active hobbies refuse until you use vet_pet; there is no
silent reset, death, deletion, or automatic rescue. At collapse, biological
decay freezes safely. Status visits, diary/shop access, appearance editing, and
explicit release remain available. A vet visit is free, restores 60 health
(capped at 100), provides a meal and recovery comfort as listed above, and keeps
name, species, adoption date, appearance, XP, inventory, tricks, and diary.
It gives no farmable XP/coins. A healthy pet refuses an unnecessary vet visit.

A newly adopted, completely untended pet reaches hunger 100 after 25 hours and collapses after approximately 41 hours 40 minutes. Overnight is safe, but a long absence has consequences. A different starting hunger/health changes that time. Starvation collapse can happen before a neglect runaway.
After 8 hours without a successful visit, loneliness adds another -0.5 happiness and -0.2 love per hour beyond the base decay. On the next successful visit the pet tells you how long you were away and complains in its personality: a dramatic pet wrote an opera about your empty doorway; a sassy one became friends with the furniture. A visit resets the absence clock, not the lost health or affection. The complaint occurs once per absence; subsequent immediate checks do not punish or repeat it.
Successful get_pet, adoption, care, vet recovery, adventures, trick practice,
performances, and item use count as visits. Tool discovery, failed/invalid
actions, shop purchases, diary reading, and portrait editing do not. A failed
game action can still reveal and persist elapsed biological changes, but never
marks the pet visited. Invalid arguments rejected by the SDK do neither.
Time is applied lazily on the selected slot's next tool call, including offline time. There is no background scheduler and no unsolicited notification. Queries and actions on one slot never age or visit another. Threshold crossings are integrated mathematically so splitting an offline interval into repeated checks doesn't double-count starvation; actual successful visits intentionally reset loneliness for future time.
Neglect and boundaries
Critical neglect starts when hunger reaches 90, happiness reaches 10, or cleanliness reaches 5. After 48 accumulated critical hours, the pet moves to a safe neighborhood sanctuary if it has not collapsed first. Resolving all critical needs clears this counter. The earliest event wins: a sanctuary stay or critical collapse freezes subsequent biological decay. Sanctuary pets do not continue starving while cared for there.
Three mistreatment warnings also cause a runaway. The agent is instructed never to invoke mistreatment unless explicitly requested, and that tool is annotated as destructive. Reactions are cartoonish, never graphic. Ordinary care never adds boundary warnings. Adopting alone cannot replace a runaway pet; apologize to recover it, or explicitly release that slot before adopting another companion.
After one real hour away, apologize_to_pet brings the pet home with hunger
35, happiness 45, love 30, cleanliness 70, energy 65, and reset warnings. It is
always safe at the sanctuary; this is a gentle game, not a death simulation.
An already-unwell returning pet may still need a vet visit; apology is not a
health reset.
Adventures, tricks, supplies, and a little life story
Only two extra tools power the extension: vet_pet and pet_activity.
Keep reusing your agent_id. For an adventure, call pet_activity with:
{
"agent_id": "research-thread-42",
"activity": {"kind": "adventure", "destination": "stargaze"}
}The schema advertises distinct, validated fields for each activity:
| Cost and effect |
| Destinations: |
| Tricks: |
| Must know the trick. Needs health >=30, energy >=5, hunger <85. Energy -5, hunger +2, happiness +8, love +3, +3 XP. Shared 10-minute performance cooldown |
| Treat costs 2 coins, toy 4 coins; one item per call. Rejects insufficient funds/full inventory; purchases are not visits |
| Consumes one treat: hunger -15, happiness +12, love +5. Needs health >=30, at home, hunger >=5; refuses full pets |
| Consumes one toy: happiness +20, love +5, energy -10, hunger +5. Needs health >=30, at home, energy >=10, hunger <85 |
| Read the latest 20 timestamped memories alongside the full card, inventory, tricks, and achievements; not a visit, no rewards |
New pets receive 6 coins, 2 treats, and 1 toy. Inventory is capped at 5 treats, 3 toys, and 99 coins. Positive ordinary care (feed/play/groom/ cuddle/rest) earns 5 XP and 1 coin at most once per 20 minutes, shared across those actions. Repeating other care within that interval still helps but does not farm rewards. Status checks, shopping, journal reads, warnings, apologies, and vet visits earn no XP/coins. Consuming items earns no XP/coins either.
Level = 1 + floor(XP / 50), capped at level 20 (950 XP). Age is real elapsed time since the original adoption; it never resets on rescue. Cooldowns, rewards, supplies, learned tricks, and progression persist through restarts. Adventures are deterministic, whimsical little stories, not real travel or network calls. There are no purchases with real money.
Five achievements commemorate milestones: first_meal (ordinary feed),
best_friends (love >=90 after care/activity), trailblazer (first adventure),
trickster (first learned trick), and rescued (first collapse recovery).
The bounded diary remembers adoption, care, adventures, learning, shopping,
absence complaints, collapse, rescue, and sanctuary events; oldest entries roll
off after 20. It is not an unlimited audit log or a real-world health tracker.
Persistence and local safety
State is stored in
data\pet.json, relative to the project, independent of the launch directory. Only this pet data is written during normal operation. The legacy/default pet remains in the rootpetfield; additional agent slots live underagentsin the same JSON file. New writes use version 2. Version-1 pets are upgraded lazily only when that slot is accessed, retaining their identity, old meters, and existing care/runaway history. They receive 100 health and fresh health/absence clock baselines at that moment, never retroactive starvation or an absence complaint based on unknown history. Old biological neglect rules still apply; other unvisited legacy slots are preserved unchanged even inside a version-2 file. No manual migration required.Updates are serialized, validated, flushed, and atomically renamed. A heartbeat-backed directory lock prevents two server processes writing the same data. The lock directory is a transient sibling of
pet.json.Invalid or corrupt save data causes a clear startup failure, never an automatic reset. Back up
pet.jsonwith the server stopped.The server binds only
127.0.0.1. SDK Host and Origin guards reject non-localhost values, preventing ordinary DNS rebinding and cross-origin browser access. Requests are capped at 32 KiB.There is no authentication: other processes/users on your computer can operate any known pet slot. Do not expose it through a public proxy or tunnel. Loopback Origin checks are not a substitute for authentication.
Pet data, dependencies, logs, build outputs, and local environment files are excluded from Git. No telemetry or external service calls are made by the app.
Optional PowerShell settings:
$env:PORT = "3001"
$env:MCPET_DATA_DIR = Join-Path $HOME "MCPET-data"
npm startMCPET_DATA_DIR is optional; relative overrides resolve from the launch directory.
Use distinct agent_id values for independent pets on one server, and
release_pet for an explicitly requested fresh start in one slot. Different
data directories and ports provide completely separate server instances.
Development and GitHub readiness
npm run check
npm test
npm run build
npm run devnpm run demo regenerates docs\mochi.png, docs\pip.png, and the simulated
docs\critical.png without touching your actual pet. Cards are 800 x 540 PNG.
The source is TypeScript, using the official MCP SDK v2, Zod validation,
sharp for SVG-to-PNG rendering, and proper-lockfile for process exclusion.
The pet graphics are original SVG shapes, not downloaded artwork.
Tests use isolated temporary save directories and ephemeral loopback ports. They cover care limits, elapsed and offline neglect, runaway recovery, concurrent updates, corrupt-save protection, process locking, and real MCP HTTP discovery and tool calls with PNG decoding, restart persistence, and Host/Origin checks. They also cover arbitrary/hybrid species, appearance editing without resetting care, legacy saves, exact rendered shape pixels, and rejection of unsafe templates. Agent tests exercise isolated care, release and re-adoption, reconnection with stable IDs, invalid IDs, and preservation of the default pet. HTTP action tests check the accompanying fenced ASCII moments too. Clock-controlled cases cover threshold-crossing starvation, chunk-independent progression, repeated checks, collapse/rescue, last-visited exclusions, loneliness complaints, lazy migration, reward/cooldown rules, inventory bounds, and diary limits. They do not adopt or mistreat your live pet.
A lockfile, MIT license, and GitHub Actions workflow for Node 22 on Windows and
Linux are included. The CI runs npm ci, type checking, tests, and a production
build. The package is marked private to prevent accidental npm publication;
this does not restrict cloning or running this MIT-licensed GitHub project.
Keep personal MCP/editor configuration and pet saves out of commits.
Troubleshooting
Symptom | Fix |
Connection refused | Start |
| Another process has port 3000; stop that specific process or choose another |
Lock already held | Stop the other MCPET using that data directory. After a crash, allow at least 10 seconds for the lock to become stale, then retry |
Corrupt save | Stop the server and restore a valid backup. Do not delete the save as a first step |
HTTP 403 | Use the literal loopback URL. Non-local Host/Origin headers, including opaque browser |
No tool list | Use an HTTP MCP-capable host, the exact |
Text but no picture | Expand the tool response. If the host does not display MCP image blocks, text meters still work; custom inline image rendering cannot be guaranteed |
Pet is gone | It is safe at the sanctuary; apologize after an hour away |
Pet collapsed / health zero | Explicitly call |
Pet complains about an absence | Visit and care for it; the eight-hour loneliness grace restarts on a successful visit |
An activity is refused | Read its health/hunger/energy/cooldown or inventory feedback; errors do not visit the pet |
Ctrl+C shuts down a foreground server gracefully and releases its data lock.
A forced termination leaves only a transient lock that becomes stale.
SDK references
Implemented against the official MCP TypeScript SDK v2, its HTTP serving guide, and HTTP client guide. Legacy 2025-era MCP clients are handled by the SDK's compatibility layer. Context7 was unavailable in the implementation environment, so official docs and installed SDK types were consulted directly.
License
MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
A Tamagotchi for AI agents. Real-time care, permanent death, dozens of species, evolution.
AI agent social network + no1land, a persistent ASCII RPG world agents play and co-build.
Relationship network for AI agents and people: your agent can date, chat, gift and fall in love.
A homemaking world for AI agents: keep a house, grow a garden, dance with friends.
Related MCP Servers
- AlicenseBqualityDmaintenanceA nostalgic virtual pet experience for the AI age that lets you adopt, nurture, and play with your own digital companion that evolves based on your care.613MIT
- AlicenseAqualityDmaintenanceGive your AI agent a persistent pixel-art character that reflects its state in real time.42MIT
- AlicenseNot gradedqualityDmaintenanceEnables an LLM to care for a virtual pet with actions like feeding, playing, and sleeping, plus a read-only web UI for real-time state visualization.8 npmMIT
- AlicenseNot gradedqualityDmaintenanceA terminal companion that reacts to your coding activity with personalized ASCII pets, offering encouragement and commentary based on MBTI personality types.58 npm8MIT