Hortusfox

A Model Context Protocol (MCP) stdio server for HortusFox, the self-hosted plant management system. It exposes the complete HortusFox REST API (/api/*) as MCP tools so AI assistants can read and manage your plants, locations, tasks, inventory, calendar, chat and backups.

Written in TypeScript for Node.js, using the official @modelcontextprotocol/sdk.

Features

Every endpoint of the HortusFox ApiController is covered — 38 tools across 7 domains:

Domain	Tools
Plants (18)	get, add, update, remove, list, search; custom attributes add/edit/remove; main photo update; gallery list/add/edit/remove; log add/edit/remove/fetch
Locations (2)	list, get info
Tasks (4)	fetch, add, edit, remove
Inventory (6)	fetch, add, edit, increment, decrement, remove
Calendar (4)	fetch, add, edit, remove
Chat (2)	fetch, post message
Backup (2)	export, import

Prerequisites

• Node.js 18+ (uses the built-in fetch).
• A running HortusFox instance.
• A HortusFox API key. In HortusFox, go to Admin → API and create a key.

Installation

npm install
npm run build

This produces the runnable server at dist/index.js.

Configuration

The server is configured entirely through environment variables:

Variable	Required	Description
HORTUSFOX_URL	✅	Base URL of your HortusFox instance, e.g. https://garden.example.com
HORTUSFOX_API_TOKEN	✅	API key created in the HortusFox admin panel
HORTUSFOX_TIMEOUT	❌	Request timeout in milliseconds (default 30000)

See .env.example.

Usage

Run directly

HORTUSFOX_URL=https://garden.example.com \
HORTUSFOX_API_TOKEN=your-token \
node dist/index.js

The server speaks MCP over stdio. Diagnostic messages are written to stderr; the JSON-RPC protocol uses stdout.

Run with npx

Once published to npm, the server can be run without a local checkout:

HORTUSFOX_URL=https://garden.example.com \
HORTUSFOX_API_TOKEN=your-token \
npx @tomfrenzel/hortusfox-mcp

Register with an MCP client

Add the server to your client's MCP configuration. The recommended way is via npx:

{
  "mcpServers": {
    "hortusfox": {
      "command": "npx",
      "args": ["-y", "@tomfrenzel/hortusfox-mcp"],
      "env": {
        "HORTUSFOX_URL": "https://garden.example.com",
        "HORTUSFOX_API_TOKEN": "your-token"
      }
    }
  }
}

Alternatively, point at a local build:

{
  "mcpServers": {
    "hortusfox": {
      "command": "node",
      "args": ["/absolute/path/to/hortusfox-mcp/dist/index.js"],
      "env": {
        "HORTUSFOX_URL": "https://garden.example.com",
        "HORTUSFOX_API_TOKEN": "your-token"
      }
    }
  }
}

If installed globally (npm install -g .), you can use the hortusfox-mcp binary instead of node dist/index.js.

Tool reference

All tools are prefixed with hortusfox_. Each returns the raw HortusFox JSON response (pretty-printed). Errors (network failures, auth rejection, or API error codes) are returned as MCP tool errors with a descriptive message.

Plants

Tool	Endpoint	Key arguments
hortusfox_get_plant	plants/get	plant
hortusfox_add_plant	plants/add	name, location
hortusfox_update_plant	plants/update	plant, attribute, value
hortusfox_remove_plant	plants/remove	plant
hortusfox_list_plants	plants/list	location?, limit?, from?, sort?
hortusfox_search_plants	plants/search	expression, limit?
hortusfox_add_plant_attribute	plants/attributes/add	plant, label, datatype, content
hortusfox_edit_plant_attribute	plants/attributes/edit	plant, label, datatype, content
hortusfox_remove_plant_attribute	plants/attributes/remove	plant, label
hortusfox_update_plant_photo	plants/photo/update	plant, external?, photo?, move_to_gallery?
hortusfox_list_plant_gallery	plants/gallery/list	plant
hortusfox_add_plant_gallery_photo	plants/gallery/add	plant, label?, external?, photo?
hortusfox_edit_plant_gallery_photo	plants/gallery/edit	plant, item, label
hortusfox_remove_plant_gallery_photo	plants/gallery/remove	item
hortusfox_add_plant_log_entry	plants/log/add	plant, content
hortusfox_edit_plant_log_entry	plants/log/edit	logid, content
hortusfox_remove_plant_log_entry	plants/log/remove	logid
hortusfox_fetch_plant_log	plants/log/fetch	plant, paginate?, limit?

Photos: the API-based photo tools support external image URLs (external: true with a photo URL). Direct binary file uploads are not exposed over the token API.

Locations

Tool	Endpoint	Key arguments
hortusfox_list_locations	locations/list	only_active?, include_plants?, include_info?, paginate?, limit?
hortusfox_get_location	locations/info	location, include_plants?

Tasks

Tool	Endpoint	Key arguments
hortusfox_fetch_tasks	tasks/fetch	done?, limit?
hortusfox_add_task	tasks/add	title, description?, due_date?, recurring_time?, recurring_scope?, plant?
hortusfox_edit_task	tasks/edit	task, title?, description?, due_date?, recurring_time?, recurring_scope?, done?
hortusfox_remove_task	tasks/remove	task

Inventory

Tool	Endpoint	Key arguments
hortusfox_fetch_inventory	inventory/fetch	–
hortusfox_add_inventory_item	inventory/add	name, description?, tags?, location?, amount?, group?, photo?
hortusfox_edit_inventory_item	inventory/edit	item, plus any of the add fields
hortusfox_increment_inventory_item	inventory/amount/inc	item
hortusfox_decrement_inventory_item	inventory/amount/dec	item
hortusfox_remove_inventory_item	inventory/remove	item

Calendar

Tool	Endpoint	Key arguments
hortusfox_fetch_calendar	calendar/fetch	date_from?, date_till?
hortusfox_add_calendar_entry	calendar/add	name, date_from, date_till?, class?
hortusfox_edit_calendar_entry	calendar/edit	ident, name?, date_from, date_till?, class?
hortusfox_remove_calendar_entry	calendar/remove	ident

Chat

Tool	Endpoint	Key arguments
hortusfox_fetch_chat	chat/fetch	limit?
hortusfox_add_chat_message	chat/message/add	message

Backup

Tool	Endpoint	Key arguments
hortusfox_export_backup	backup/export	locations?, plants?, gallery?, tasks?, inventory?, calendar?
hortusfox_import_backup	backup/import	same category flags

Development

npm run dev        # tsc --watch
npm run typecheck  # type-check without emitting
npm run build      # compile to dist/

A dev container config is provided in .devcontainer/ for a ready-to-use Node.js + TypeScript environment.

Releasing

Releases are published to npm automatically by the Release GitHub Actions workflow whenever a v* tag is pushed. The workflow type-checks, builds, verifies the tag matches the package.json version, and publishes with npm provenance.

To cut a release:

npm version patch   # or minor / major — bumps package.json and creates a tag
git push --follow-tags

This requires an NPM_TOKEN secret to be configured in the repository settings.

How it works

The Asatru framework behind HortusFox merges POST body, query string and JSON body into a single request argument bag, and the API authenticates via a token parameter. This server therefore sends each request as an application/x-www-form-urlencoded POST (including the token and all parameters), which works uniformly for every route and avoids URL-length limits for larger text fields. Requests are retried up to 3 times on transient network/timeout failures; deterministic API and auth errors are surfaced immediately.

License

MIT — see LICENSE.