pls-touch-grass-mcp
An MCP server that knows how long it's been since you touched grass, and won't shut up about it.
You log grass, it tracks indoor time, it catches you raging at your AI and sends you to the nearest park, weather checked first. A joke, but one that teaches MCP: five tools, shared state, and descriptions that make the model call them unprompted.
Install
Claude Code
claude mcp add pls-touch-grass -s user -- npx -y pls-touch-grass-mcp
-s user, or the server only exists in the directory you ran that from. Working from
a clone, skip the command: there's a .mcp.json in the root and Claude Code offers it
when you open the folder.
Cursor
Or the JSON, in ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):
{
"mcpServers": {
"pls-touch-grass": {
"command": "npx",
"args": ["-y", "pls-touch-grass-mcp"]
}
}
}
Claude Desktop
.mcpb from Releases, then
Settings → Extensions → Install Extension. Dependencies are bundled; installs offline.
By hand it's the same JSON as Cursor, in claude_desktop_config.json
(~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows).
claude.ai
No. Custom connectors want a remote server over HTTPS; this is stdio on your own machine. HTTP transport is the first item under Homework.
From source
git clone https://github.com/Rinava/pls-touch-grass-mcp
cd pls-touch-grass-mcp
npm ci && npm run build
Point any config above at node /absolute/path/to/dist/index.js instead.
npx -y downloads the package on first start — live audiences and venue wifi deserve
a warm cache. Published on npm as pls-touch-grass-mcp, in the MCP Registry as
io.github.Rinava/pls-touch-grass.
The five tools
| Tool | What it does | When the model calls it |
|---|---|---|
touched_grass | Logs that you went outside | "back from the park" |
gotta_go | Do you need to go out? | "can I keep going?" |
frustration_detector | Catches the rage and escalates | on its own, when you snap; that's the point |
grass_conditions | Real weather (Open-Meteo, no key) | before sending you outside |
where_to_touch_grass | Nearby parks with distances (OpenStreetMap) | "where should I go?", or when you name a place |
Nobody teaches the model to detect frustration: the tool description does it alone. Type "NOTHING WORKS!!!" and watch.
Zero configuration
Location resolves fresh from your IP (ipwho.is) each run —
city-level on purpose. Detection down: last known spot, then the Obelisco, like
everyone else. Name a neighborhood or a street address to where_to_touch_grass and
it sticks: known neighborhoods resolve offline, anything else is geocoded once through
OpenStreetMap's Nominatim, and only the words you typed leave your machine. A place
you named outranks a guess from your IP, until you name a different one.
Indoor tolerance defaults to a merciless 2 minutes; ask the model for clemency and it
passes a bigger threshold_minutes to gotta_go. State is one JSON file,
~/.pls-touch-grass.json. Touching grass resets the rage counter. That's how
absolution works.
The demo curse
Live demos summon it: the venue wifi dies the moment you say "watch this". Add
--demo to the args and every answer goes canned — 22°C and clear, the Obelisco,
the curated spots. Zero network calls, zero surprises. Off by default; real life
should stay real.
Follow the workshop
The repo is tagged by step:
git checkout step-1 # stdio server + touched_grass
git checkout step-2 # + gotta_go (state and threshold)
git checkout step-3 # + frustration_detector (the demo)
git checkout step-4 # + grass_conditions (network with fallback)
git checkout step-5 # + where_to_touch_grass and this README
npm ci && npm test
Every step compiles and passes its own tests. Two dependencies total: the official MCP SDK and zod.
Homework
- HTTP transport:
createMcpHandlerin SDK v2 serves the same factory over fetch, and it's what gets you onto claude.ai - Per-project thresholds instead of a global one
- Streak tracking for consecutive grass days
- Demo spots for your own city, via PR: one object per park in
src/lib/demo.ts, with an opinion
Release
npm run build:mcpb packs dist and the production dependencies into
pls-touch-grass-mcp-<version>.mcpb, the file that goes on a GitHub Release. The
manifest is generated from package.json; nothing to keep in sync by hand.
Contributing
Issues and PRs welcome — the Homework list is seeded as
open issues, several
tagged good first issue. See CONTRIBUTING.md for setup and
the house rules (there are few, but the demo-spot opinion is mandatory).
License
MIT. The grass is free and so is this.