# HortusFox MCP Server 🌿🦊

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [HortusFox](https://github.com/danielbrendel/hortusfox-web), the self-hosted collaborative plant management system.

Connect your AI coding assistants (Claude Code, Cursor, Antigravity, OpenCode, Windsurf) directly to your home garden database to inspect plant health, query watering schedules, log care events, and update timestamps.

> _Note: This project is open-source, community-driven, and was vibe-coded / AI-assisted with Google Antigravity pair programming._

---

## Features

- **Flexible Connectivity**: Connect to local LAN instances or remote instances behind reverse proxies and authentication gateways.
- **Rich Care Tools**:
  - `list_plants`: Overview of active plants, species, locations, and care dates.
  - `get_plant_details`: In-depth attributes (both default and custom fields like "Last pruned", "Soil moisture", etc.).
  - `get_plant_history`: Full audit trail of care logs, measurements, and status updates.
  - `add_plant_log`: Record watering, repotting, or health observations directly from conversation, with automatic timestamp synchronization!
  - `search_plants`: Fuzzy search across botanical names, common names, and tags.
  - `list_locations`: Discover garden zones (e.g. Indoor, Balcony, Greenhouse).
  - `update_plant_attribute`: Modify attributes (`last_watered`, `last_repotted`, `health_state`, `notes`).
  - `list_inventory` & `update_inventory_amount`: Monitor and update garden supplies and substrate stock.

---

## Tool Reference

| Tool                      | Arguments                                                                                                            | Description                                                                                        |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |
| `list_plants`             | `location_id` _(optional)_, `limit` _(optional)_                                                                     | Retrieve active plants and their care status.                                                      |
| `get_plant_details`       | `plant_id` _(required)_                                                                                              | Get comprehensive plant specs and custom attributes.                                               |
| `get_plant_history`       | `plant_id` _(required)_, `limit` _(optional)_                                                                        | Fetch historical activity logs and notes for a plant.                                              |
| `add_plant_log`           | `plant_id` _(required)_, `notes` _(required)_, `action` _(optional)_, `update_timestamp` _(optional, default: true)_ | Add care note. If action is `watered`, `fertilized`, or `repotted`, auto-updates the plant's date! |
| `search_plants`           | `query` _(required)_, `limit` _(optional)_                                                                           | Search plants across all locations.                                                                |
| `list_locations`          | _None_                                                                                                               | List all registered growing locations.                                                             |
| `update_plant_attribute`  | `plant_id` _(required)_, `attribute` _(required)_, `value` _(required)_                                              | Directly update an attribute (e.g. `last_watered: "2026-09-05"`).                                  |
| `list_inventory`          | `group` _(optional)_                                                                                                 | Retrieve inventory items (fertilizers, substrates, pest control, supplies) and stock counts.       |
| `update_inventory_amount` | `item_id` _(required)_, `action` _(required: 'inc' \| 'dec')_                                                        | Increment or decrement stock count of an inventory item.                                           |

---

## Prerequisites

1. **Node.js** 18+ and **npm**.
2. **HortusFox** v3.1+ instance with API enabled:
   - In HortusFox, navigate to **Admin Panel -> API**.
   - Generate an API Key.

---

## Installation & Build

```bash
git clone https://github.com/gotylergo/hortusfox-mcp.git # or local folder
cd hortusfox-mcp
npm install
npm run build
```

The compiled server entrypoint is located at `dist/index.js`.

---

## Configuration & Environment Variables

| Variable                   | Description                                                                       | Example                                                 |
| :------------------------- | :-------------------------------------------------------------------------------- | :------------------------------------------------------ |
| `HORTUSFOX_URL`            | Base URL of your HortusFox instance.                                              | `http://localhost:8080` or `https://plants.example.com` |
| `HORTUSFOX_API_TOKEN`      | HortusFox API token generated in Admin -> API.                                    | `your_api_token_here`                                   |
| `HORTUSFOX_CUSTOM_HEADERS` | _(Optional)_ JSON map of custom HTTP headers (e.g. reverse proxy or auth tokens). | `{"X-Custom-Auth":"secret"}`                            |
| `CF_ACCESS_CLIENT_ID`      | _(Optional)_ Shorthand for Cloudflare Access Service Token Client ID.             | `xxxx.access`                                           |
| `CF_ACCESS_CLIENT_SECRET`  | _(Optional)_ Shorthand for Cloudflare Access Service Token Client Secret.         | `xxxx`                                                  |

---

## Registering with MCP Clients

### Claude Desktop / Claude Code (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "hortusfox": {
      "command": "node",
      "args": ["/absolute/path/to/hortusfox-mcp/dist/index.js"],
      "env": {
        "HORTUSFOX_URL": "http://localhost:8080",
        "HORTUSFOX_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "hortusfox": {
      "command": "node",
      "args": ["/absolute/path/to/hortusfox-mcp/dist/index.js"],
      "env": {
        "HORTUSFOX_URL": "http://localhost:8080",
        "HORTUSFOX_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}
```

### Antigravity / Gemini CLI (`~/.gemini/antigravity/mcp_config.json`)

```json
{
  "mcpServers": {
    "hortusfox": {
      "command": "node",
      "args": ["/absolute/path/to/hortusfox-mcp/dist/index.js"],
      "env": {
        "HORTUSFOX_URL": "http://localhost:8080",
        "HORTUSFOX_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}
```

### OpenCode (`~/.config/opencode/opencode.jsonc`)

```jsonc
{
  "mcp": {
    "hortusfox": {
      "type": "local",
      "command": ["node", "/absolute/path/to/hortusfox-mcp/dist/index.js"],
      "environment": {
        "HORTUSFOX_URL": "http://localhost:8080",
        "HORTUSFOX_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}
```

---

## Authentication Proxies & Custom Headers

If your HortusFox instance is protected by an authentication gateway (such as Cloudflare Access, Authelia, or an OAuth proxy), pass custom headers via `HORTUSFOX_CUSTOM_HEADERS`:

```json
"env": {
  "HORTUSFOX_URL": "https://plants.example.com",
  "HORTUSFOX_API_TOKEN": "YOUR_API_TOKEN",
  "HORTUSFOX_CUSTOM_HEADERS": "{\"CF-Access-Client-Id\": \"...\", \"CF-Access-Client-Secret\": \"...\"}"
}
```

For Cloudflare Access specifically, `CF_ACCESS_CLIENT_ID` and `CF_ACCESS_CLIENT_SECRET` can also be supplied directly as environment variables.

---

## License

MIT