Pls Touch Grass

What pls-touch-grass MCP server does

The pls-touch-grass MCP server exposes five tools for tracking and encouraging time outdoors:

• touched_grass records that the user went outside and resets the frustration count.
• gotta_go checks whether the user has spent longer indoors than the allowed threshold.
• frustration_detector reacts to messages that indicate the user is becoming angry and escalates without requiring a separate instruction.
• grass_conditions retrieves current weather conditions.
• where_to_touch_grass finds nearby parks and reports distances.

The server is intentionally small and illustrative. Its main value is showing how MCP tool descriptions, shared state, thresholds, and network-backed tools can work together. It can also support a playful workflow in which an agent notices frustration, checks the weather, and recommends somewhere nearby to go.

How it works

The pls-touch-grass MCP server uses stdio transport and is normally started with npx -y pls-touch-grass-mcp. State is kept in ~/.pls-touch-grass.json, so the indoor timer, last known location, selected place, and frustration tracking can persist between calls.

Location is resolved from the client machine's IP address through ipwho.is, at city-level precision. If that lookup fails, the server uses the last known location and then a fixed fallback location. Supplying a neighborhood or street address to where_to_touch_grass takes precedence. Known neighborhoods can resolve locally; other places are looked up once through OpenStreetMap's Nominatim service.

Weather data comes from Open-Meteo and park information comes from OpenStreetMap. Neither service requires an API key according to the project documentation. The default indoor threshold is two minutes, but the model can pass a larger threshold_minutes value to gotta_go.

A --demo argument switches responses to canned data, including fixed weather and curated locations. Demo mode makes no network calls and is off by default.

Setup and configuration

For Claude Code, register the server with:

claude mcp add pls-touch-grass -s user -- npx -y pls-touch-grass-mcp

Cursor can use the same command and arguments in its global or project MCP configuration. Claude Desktop can install the .mcpb package from a release, or use an equivalent stdio JSON configuration. When using a source checkout, run npm ci && npm run build, then configure the client to execute node /absolute/path/to/dist/index.js.

The published package is available through npm, and the project also has an MCP Registry entry. No environment variables are required. Add --demo to the configured arguments when deterministic, offline responses are needed.

The pls-touch-grass MCP server does not provide an HTTPS transport in the documented implementation, so it cannot be used directly as a custom connector for claude.ai. The repository lists HTTP transport as future work.