This MCP server exposes the complete HortusFox REST API as tools, enabling AI assistants to manage a self-hosted plant management system across 7 domains:
Plants: Get details, add, update, or remove plants; list with filtering/pagination/sorting; free-text search; manage custom attributes; update main photo; manage gallery photos; add, edit, remove, or fetch plant log/journal entries.
Locations: List all locations (with optional plant counts/lists) and get details of a specific location.
Tasks: Fetch tasks (including completed ones), add with optional due dates, recurrence, and plant associations, edit (including toggling completion), and remove.
Inventory: Fetch full inventory, add new items, edit existing items, increment/decrement item amounts, and remove items.
Calendar: Fetch entries within a date range, add entries with start/end dates and optional class, edit, and remove.
Chat: Fetch recent workspace chat messages and post new messages as a bot.
Backup: Export backup archives for selected data categories (locations, plants, gallery, tasks, inventory, calendar) and import previously staged backup data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hortusfox-mcp list all plants in the living room"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Every endpoint of the HortusFox ApiController is covered — 42 tools across 7 domains:
Domain | Tools |
Plants (22) | get, add, update, remove, list, search; custom attributes add/edit/remove; main photo update; gallery list/add/edit/remove; attachments fetch/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 |
Related MCP server: MCP Enterprise Architecture Practice 01
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.
npm install
npm run buildThis produces the runnable server at dist/index.js.
The server is configured entirely through environment variables:
Variable | Required | Description |
| ✅ | Base URL of your HortusFox instance, e.g. |
| ✅ | API key created in the HortusFox admin panel |
| ❌ | Request timeout in milliseconds (default |
| ❌ | Directory local files may be uploaded from. Unset, every upload is refused |
| ❌ | Upload size ceiling in MiB (default |
See .env.example.
HORTUSFOX_URL=https://garden.example.com \
HORTUSFOX_API_TOKEN=your-token \
node dist/index.jsThe server speaks MCP over stdio. Diagnostic messages are written to stderr; the
JSON-RPC protocol uses stdout.
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-mcpAdd 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.
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.
Tool | Endpoint | Key arguments |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Photos and attachments: the photo tools accept either an external image URL (
external: truewith aphotoURL) or a local file (path), sent asmultipart/form-data. Attachments are always local files. Local uploads are only allowed fromHORTUSFOX_UPLOAD_DIR: the path is resolved withrealpathfirst, so neither..nor a symlink can reach outside it, and files aboveHORTUSFOX_MAX_UPLOAD_MBare refused before being read.
Tool | Endpoint | Key arguments |
|
|
|
|
|
|
Tool | Endpoint | Key arguments |
|
|
|
|
|
|
|
|
|
|
|
|
Tool | Endpoint | Key arguments |
|
| – |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Tool | Endpoint | Key arguments |
|
|
|
|
|
|
|
|
|
|
|
|
Tool | Endpoint | Key arguments |
|
|
|
|
|
|
Tool | Endpoint | Key arguments |
|
|
|
|
| same category flags |
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.
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-tagsThis requires an NPM_TOKEN secret to be configured in the repository settings.
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.
MIT — see LICENSE.
Add a calendar entry with a name, start date and optional end date and class. Returns the new item ID. Endpoint: /api/calendar/add.
Inputs: name (required), date_from (required), class, date_till.
Post a message to the workspace chat (sent via the API/bot identity). Endpoint: /api/chat/message/add.
Inputs: message (required).
Add a new inventory item. Returns the new item ID. Endpoint: /api/inventory/add.
Inputs: name (required), tags, group, photo, +3 more.
Create a new plant with a name and a location ID. Returns the new plant ID. Endpoint: /api/plants/add.
Inputs: name (required), location (required).
Add a custom attribute to a plant. Endpoint: /api/plants/attributes/add.
Inputs: label (required), plant (required), content (required), datatype (required).
Add a photo to a plant gallery. Set external=true and provide a photo URL to add an external image. Endpoint: /api/plants/gallery/add.
Inputs: plant (required), label, photo, external.
Add a log/journal entry to a plant. Returns the new log entry ID. Endpoint: /api/plants/log/add.
Inputs: plant (required), content (required).
Create a task. Supports an optional due date, recurrence, and association with a plant. Returns the new task ID. Endpoint: /api/tasks/add.
Inputs: title (required), plant, due_date, description, +2 more.
Decrement the amount of an inventory item by one. Returns the new amount. Endpoint: /api/inventory/amount/dec.
Inputs: item (required).
Edit an existing calendar entry by its identifier. Endpoint: /api/calendar/edit.
Inputs: ident (required), date_from (required), name, class, +1 more.
Edit an existing inventory item by ID. Endpoint: /api/inventory/edit.
Inputs: item (required), name, tags, group, +4 more.
Edit an existing custom attribute of a plant, identified by its label. Endpoint: /api/plants/attributes/edit.
Inputs: label (required), plant (required), content (required), datatype (required).
Edit the label of a gallery photo item. Endpoint: /api/plants/gallery/edit.
Inputs: item (required), label (required), plant (required).
Edit an existing plant log entry by its ID. Endpoint: /api/plants/log/edit.
Inputs: logid (required), content (required).
Edit an existing task by ID, including toggling its done state. Endpoint: /api/tasks/edit.
Inputs: task (required), done, title, due_date, +3 more.
Export a backup archive for the selected data categories. Returns a downloadable file URL. Endpoint: /api/backup/export.
Inputs: tasks, plants, gallery, calendar, +2 more.
Fetch calendar entries within a date range. Defaults to today through the next 30 days when omitted. Endpoint: /api/calendar/fetch.
Inputs: date_from, date_till.
Fetch recent workspace chat messages. Endpoint: /api/chat/fetch.
Inputs: limit.
Fetch the full inventory list. Endpoint: /api/inventory/fetch.
Inputs: no named parameters.
Fetch log entries for a plant, with optional pagination. Endpoint: /api/plants/log/fetch.
Inputs: plant (required), limit, paginate.
Fetch tasks, optionally including completed ones. Endpoint: /api/tasks/fetch.
Inputs: done, limit.
Fetch details of a single location by ID, optionally including its plants. Endpoint: /api/locations/info.
Inputs: location (required), include_plants.
Fetch full details of a single plant by its ID, including default fields and any custom attributes. Endpoint: /api/plants/get.
Inputs: plant (required).
Import previously staged backup data for the selected categories. Endpoint: /api/backup/import.
Inputs: tasks, plants, gallery, calendar, +2 more.
Increment the amount of an inventory item by one. Returns the new amount. Endpoint: /api/inventory/amount/inc.
Inputs: item (required).
List locations, optionally including the plants at each location. Endpoint: /api/locations/list.
Inputs: limit, paginate, only_active, include_info, +1 more.
List all gallery photos for a plant. Endpoint: /api/plants/gallery/list.
Inputs: plant (required).
List plants, optionally filtered by location, with paging and sorting. Endpoint: /api/plants/list.
Inputs: from, sort, limit, location.
Remove a calendar entry by its identifier. Endpoint: /api/calendar/remove.
Inputs: ident (required).
Remove an inventory item by ID. Endpoint: /api/inventory/remove.
Inputs: item (required).
Delete a plant by its ID. Endpoint: /api/plants/remove.
Inputs: plant (required).
Remove a custom attribute from a plant by its label. Endpoint: /api/plants/attributes/remove.
Inputs: label (required), plant (required).
Remove a gallery photo by its item ID. Endpoint: /api/plants/gallery/remove.
Inputs: item (required).
Remove a plant log entry by its ID. Endpoint: /api/plants/log/remove.
Inputs: logid (required).
Remove a task by ID. Endpoint: /api/tasks/remove.
Inputs: task (required).
Search plants by a free-text expression (matches name, location, attributes and more). Endpoint: /api/plants/search.
Inputs: expression (required), limit.
Update a single attribute of a plant by name (e.g. name, location, description, humidity, etc.). Endpoint: /api/plants/update.
Inputs: plant (required), value (required), attribute (required).
Update the main preview photo of a plant. Set external=true and provide a photo URL to use an external image. Optionally move the current photo into the gallery first. Endpoint: /api/plants/photo/update.
Inputs: plant (required), photo, external, move_to_gallery.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 38 tools
Most tools are clearly separated by resource and action, so an agent can usually pick the right one. The main overlap is hortusfox_update_plant vs hortusfox_edit_plant_attribute, both of which can look like attribute modification, and the numerous read variants (get/list/fetch/search) require careful description reading.
Every tool uses the hortusfox_<verb>_<noun> snake_case pattern, and CRUD verbs are mostly consistent. However, reads mix get, list, fetch, and search, and modifications mix update and edit, so the verb choice is not fully predictable.
38 tools is a high count, but it is organized into logical modules (plants, locations, calendar, tasks, inventory, chat, backup) and each tool maps to a distinct endpoint. Even so, the set is larger than ideal for an MCP server and may feel heavy to an agent.
Core plant management is well covered: plant CRUD, custom attributes, gallery photos, log entries, plus tasks, calendar, inventory, and backup. The notable gap is locations only support list/get, with no create/update/delete, which can block workflows that need to set up or modify locations.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Hosted MCP server for live public-data APIs and Skills for AI agents.
