# pls-touch-grass [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/Rinava/pls-touch-grass-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 213  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/pls-touch-grass

## Description
An MCP server that knows how long it's been since you touched grass

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "pls-touch-grass": {
    "command": "npx",
    "args": ["-y","pls-touch-grass-mcp"]
  }
}
```

## Documentation

## 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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/pls-touch-grass/readme_