grocy-mcp-server 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,8 @@
1
+ # Copy to .env for local runs, or pass these to Docker with -e.
2
+ # Never commit a real .env — it contains your API key.
3
+
4
+ # Base URL of your Grocy instance (no trailing slash needed)
5
+ GROCY_URL=https://grocy.example.com
6
+
7
+ # Grocy API key: Settings -> Manage API keys -> Add
8
+ GROCY_KEY=replace-with-your-api-key
@@ -0,0 +1,68 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [master, main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ fail-fast: false
13
+ matrix:
14
+ python-version: ["3.10", "3.12"]
15
+
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+
19
+ - uses: actions/setup-python@v5
20
+ with:
21
+ python-version: ${{ matrix.python-version }}
22
+ cache: pip
23
+
24
+ - name: Install package with dev extras
25
+ run: |
26
+ python -m pip install --upgrade pip
27
+ pip install -e ".[dev]"
28
+
29
+ - name: Run tests
30
+ # The tests stub the transport, so no Grocy instance is needed.
31
+ run: pytest tests/ -q
32
+
33
+ build:
34
+ runs-on: ubuntu-latest
35
+ steps:
36
+ - uses: actions/checkout@v4
37
+
38
+ - uses: actions/setup-python@v5
39
+ with:
40
+ python-version: "3.12"
41
+
42
+ - name: Build sdist and wheel
43
+ run: |
44
+ python -m pip install --upgrade pip build
45
+ python -m build
46
+
47
+ - name: Check the wheel installs and exposes the console script
48
+ run: |
49
+ python -m venv /tmp/verify
50
+ /tmp/verify/bin/pip install dist/*.whl
51
+ /tmp/verify/bin/grocy-mcp-server 2>&1 | grep -q "GROCY_URL and GROCY_KEY must be set"
52
+
53
+ - uses: actions/upload-artifact@v4
54
+ with:
55
+ name: dist
56
+ path: dist/
57
+
58
+ docker:
59
+ runs-on: ubuntu-latest
60
+ steps:
61
+ - uses: actions/checkout@v4
62
+
63
+ - name: Build image
64
+ run: docker build -t grocy-mcp:ci .
65
+
66
+ - name: Container starts and reports missing config
67
+ run: |
68
+ docker run --rm grocy-mcp:ci 2>&1 | grep -q "GROCY_URL and GROCY_KEY must be set"
@@ -0,0 +1,49 @@
1
+ name: Publish
2
+
3
+ # Publishing is manual: bump the version in pyproject.toml, tag, and push the tag.
4
+ on:
5
+ push:
6
+ tags: ["v*"]
7
+
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+
14
+ - uses: actions/setup-python@v5
15
+ with:
16
+ python-version: "3.12"
17
+
18
+ - name: Build
19
+ run: |
20
+ python -m pip install --upgrade pip build
21
+ python -m build
22
+
23
+ - name: Verify the tag matches the package version
24
+ run: |
25
+ python - <<'PY'
26
+ import os, tomllib
27
+ version = tomllib.load(open("pyproject.toml", "rb"))["project"]["version"]
28
+ tag = os.environ["GITHUB_REF_NAME"].lstrip("v")
29
+ assert version == tag, f"tag {tag} != pyproject version {version}"
30
+ PY
31
+
32
+ - uses: actions/upload-artifact@v4
33
+ with:
34
+ name: dist
35
+ path: dist/
36
+
37
+ publish:
38
+ needs: build
39
+ runs-on: ubuntu-latest
40
+ environment: pypi
41
+ permissions:
42
+ id-token: write # PyPI trusted publishing, no API token needed
43
+ steps:
44
+ - uses: actions/download-artifact@v4
45
+ with:
46
+ name: dist
47
+ path: dist/
48
+
49
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,11 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ venv/
5
+ .env
6
+ .pytest_cache/
7
+ .ruff_cache/
8
+ build/
9
+ dist/
10
+ *.egg-info/
11
+ .worktrees/
@@ -0,0 +1,11 @@
1
+ FROM python:3.12-slim
2
+
3
+ WORKDIR /app
4
+
5
+ # Install the package itself so dependencies and the console script both come
6
+ # from pyproject.toml rather than a parallel requirements file.
7
+ COPY pyproject.toml README.md LICENSE ./
8
+ COPY grocy_mcp_server ./grocy_mcp_server
9
+ RUN pip install --no-cache-dir .
10
+
11
+ ENTRYPOINT ["grocy-mcp-server"]
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mark Arslan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,207 @@
1
+ Metadata-Version: 2.5
2
+ Name: grocy-mcp-server
3
+ Version: 1.0.0
4
+ Summary: MCP server for Grocy: stock, products, shopping lists, chores, locations and recipes
5
+ Project-URL: Homepage, https://github.com/margosmark/grocy-mcp-server
6
+ Project-URL: Issues, https://github.com/margosmark/grocy-mcp-server/issues
7
+ Author: Mark Arslan
8
+ License: MIT License
9
+
10
+ Copyright (c) 2026 Mark Arslan
11
+
12
+ Permission is hereby granted, free of charge, to any person obtaining a copy
13
+ of this software and associated documentation files (the "Software"), to deal
14
+ in the Software without restriction, including without limitation the rights
15
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
16
+ copies of the Software, and to permit persons to whom the Software is
17
+ furnished to do so, subject to the following conditions:
18
+
19
+ The above copyright notice and this permission notice shall be included in all
20
+ copies or substantial portions of the Software.
21
+
22
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
25
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
27
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28
+ SOFTWARE.
29
+ License-File: LICENSE
30
+ Keywords: grocy,household,inventory,mcp,model-context-protocol,self-hosted
31
+ Classifier: Development Status :: 4 - Beta
32
+ Classifier: Intended Audience :: End Users/Desktop
33
+ Classifier: License :: OSI Approved :: MIT License
34
+ Classifier: Programming Language :: Python :: 3
35
+ Classifier: Programming Language :: Python :: 3.10
36
+ Classifier: Programming Language :: Python :: 3.11
37
+ Classifier: Programming Language :: Python :: 3.12
38
+ Classifier: Topic :: Home Automation
39
+ Classifier: Typing :: Typed
40
+ Requires-Python: >=3.10
41
+ Requires-Dist: fastmcp>=4.0.0
42
+ Requires-Dist: httpx>=0.27.0
43
+ Provides-Extra: dev
44
+ Requires-Dist: pytest>=8.0; extra == 'dev'
45
+ Description-Content-Type: text/markdown
46
+
47
+ # grocy-mcp-server
48
+
49
+ A [Model Context Protocol](https://modelcontextprotocol.io) server for
50
+ [Grocy](https://grocy.info) — the self-hosted household ERP: stock, products,
51
+ shopping lists, chores, locations, stores and recipes.
52
+
53
+ Built for Grocy **4.x** (tested against 4.7.1). Read-only-capable: the tools are
54
+ annotated so MCP clients can tell reads from writes from destructive actions.
55
+
56
+ ```
57
+ 26 tools: stock (8) · products (4) · shopping list (6) · locations (1)
58
+ product groups (1) · quantity units (1) · stores (1) · chores (1)
59
+ recipes (2) · system (1)
60
+ ```
61
+
62
+ ## Why this one
63
+
64
+ The most-used Grocy MCP servers are no longer maintained:
65
+
66
+ - `saya6k/mcp-grocy-api` — **archived**, README marked unmaintained
67
+ - `attmous/grocy-mcp` — last release April 2026; its
68
+ [#10](https://github.com/attmous/grocy-mcp/issues/10) reports the
69
+ `expiring_products` key removal on Grocy 4.x, unanswered
70
+
71
+ This server handles the Grocy 4.x `/api/stock/volatile` shape (a single object
72
+ keyed by category) rather than assuming a flat list, which is the failure mode
73
+ in the servers above.
74
+
75
+ ## Install
76
+
77
+ Requires Python 3.10+.
78
+
79
+ ### pip
80
+
81
+ ```bash
82
+ pip install grocy-mcp-server
83
+ GROCY_URL=https://grocy.example.com GROCY_KEY=your-api-key grocy-mcp-server
84
+ ```
85
+
86
+ ### uvx (no install)
87
+
88
+ ```bash
89
+ uvx --from grocy-mcp-server grocy-mcp-server
90
+ ```
91
+
92
+ ### Docker
93
+
94
+ ```bash
95
+ docker build -t grocy-mcp .
96
+ docker run --rm -i \
97
+ -e GROCY_URL=https://grocy.example.com \
98
+ -e GROCY_KEY=your-api-key \
99
+ grocy-mcp
100
+ ```
101
+
102
+ ### From source
103
+
104
+ ```bash
105
+ git clone https://github.com/margosmark/grocy-mcp-server.git
106
+ cd grocy-mcp-server
107
+ python3 -m venv .venv && . .venv/bin/activate
108
+ pip install -e .
109
+ grocy-mcp-server
110
+ ```
111
+
112
+ ## Configuration
113
+
114
+ | Variable | Required | Description |
115
+ |---|---|---|
116
+ | `GROCY_URL` | yes | Base URL of your Grocy instance, no trailing slash needed |
117
+ | `GROCY_KEY` | yes | Grocy API key — Settings → Manage API keys → Add |
118
+
119
+ The key is sent as the `GROCY-API-KEY` header. Use a dedicated key so you can
120
+ revoke it without disturbing anything else.
121
+
122
+ ## Client setup
123
+
124
+ **Claude Desktop / Cursor / any MCP client (stdio):**
125
+
126
+ After `pip install grocy-mcp-server`, point the client at the console script:
127
+
128
+ ```json
129
+ {
130
+ "mcpServers": {
131
+ "grocy": {
132
+ "command": "grocy-mcp-server",
133
+ "env": {
134
+ "GROCY_URL": "https://grocy.example.com",
135
+ "GROCY_KEY": "your-api-key"
136
+ }
137
+ }
138
+ }
139
+ }
140
+ ```
141
+
142
+ Running from a checkout instead:
143
+
144
+ ```json
145
+ {
146
+ "mcpServers": {
147
+ "grocy": {
148
+ "command": "python3",
149
+ "args": ["-m", "grocy_mcp_server"],
150
+ "env": {
151
+ "GROCY_URL": "https://grocy.example.com",
152
+ "GROCY_KEY": "your-api-key"
153
+ }
154
+ }
155
+ }
156
+ }
157
+ ```
158
+
159
+ ## Tools
160
+
161
+ ### Stock
162
+ - `grocy_get_stock` — everything in stock with quantities, locations and due dates
163
+ - `grocy_get_stock_volatile` — overdue / due soon / expired / missing, grouped
164
+ - `grocy_get_product_stock` — stock detail for one product
165
+ - `grocy_add_stock` — add stock (amount, location, optional best-before)
166
+ - `grocy_consume_stock` — consume stock
167
+ - `grocy_transfer_stock` — move stock between locations
168
+ - `grocy_set_stock` — inventory correction (overwrites the count)
169
+ - `grocy_open_stock` — mark items as opened
170
+
171
+ ### Products
172
+ - `grocy_list_products` — list or search by name
173
+ - `grocy_get_product` — full product record
174
+ - `grocy_create_product` — create a product
175
+ - `grocy_delete_product` — delete a product *(destructive)*
176
+
177
+ ### Shopping list
178
+ - `grocy_get_shopping_list`
179
+ - `grocy_add_to_shopping_list`
180
+ - `grocy_add_note_to_shopping_list` — free text, no product needed
181
+ - `grocy_remove_from_shopping_list`
182
+ - `grocy_clear_shopping_list` *(destructive)*
183
+ - `grocy_add_missing_to_shopping_list` — everything below minimum stock
184
+
185
+ ### Lookups
186
+ `grocy_list_locations`, `grocy_list_product_groups`,
187
+ `grocy_list_quantity_units`, `grocy_list_shopping_locations`,
188
+ `grocy_list_chores`, `grocy_list_grocy_recipes`, `grocy_get_system_info`
189
+
190
+ ### Recipes
191
+ - `grocy_add_recipe_to_shopping_list` — add a recipe's missing ingredients
192
+
193
+ IDs are instance-specific. Every tool that takes an ID has a matching list tool;
194
+ resolve IDs at call time rather than hardcoding them.
195
+
196
+ ## Notes and limitations
197
+
198
+ - Recipes are read-only and basic — Grocy's recipe API is thin. Use a dedicated
199
+ recipe server if you need full recipe management.
200
+ - `grocy_set_stock` performs an inventory correction and overwrites the current
201
+ amount. Prefer `grocy_add_stock` / `grocy_consume_stock` for normal changes.
202
+ - Tested against Grocy 4.7.1. Older 3.x instances may differ in the volatile
203
+ stock response shape; both the 4.x object shape and a flat list are handled.
204
+
205
+ ## License
206
+
207
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,161 @@
1
+ # grocy-mcp-server
2
+
3
+ A [Model Context Protocol](https://modelcontextprotocol.io) server for
4
+ [Grocy](https://grocy.info) — the self-hosted household ERP: stock, products,
5
+ shopping lists, chores, locations, stores and recipes.
6
+
7
+ Built for Grocy **4.x** (tested against 4.7.1). Read-only-capable: the tools are
8
+ annotated so MCP clients can tell reads from writes from destructive actions.
9
+
10
+ ```
11
+ 26 tools: stock (8) · products (4) · shopping list (6) · locations (1)
12
+ product groups (1) · quantity units (1) · stores (1) · chores (1)
13
+ recipes (2) · system (1)
14
+ ```
15
+
16
+ ## Why this one
17
+
18
+ The most-used Grocy MCP servers are no longer maintained:
19
+
20
+ - `saya6k/mcp-grocy-api` — **archived**, README marked unmaintained
21
+ - `attmous/grocy-mcp` — last release April 2026; its
22
+ [#10](https://github.com/attmous/grocy-mcp/issues/10) reports the
23
+ `expiring_products` key removal on Grocy 4.x, unanswered
24
+
25
+ This server handles the Grocy 4.x `/api/stock/volatile` shape (a single object
26
+ keyed by category) rather than assuming a flat list, which is the failure mode
27
+ in the servers above.
28
+
29
+ ## Install
30
+
31
+ Requires Python 3.10+.
32
+
33
+ ### pip
34
+
35
+ ```bash
36
+ pip install grocy-mcp-server
37
+ GROCY_URL=https://grocy.example.com GROCY_KEY=your-api-key grocy-mcp-server
38
+ ```
39
+
40
+ ### uvx (no install)
41
+
42
+ ```bash
43
+ uvx --from grocy-mcp-server grocy-mcp-server
44
+ ```
45
+
46
+ ### Docker
47
+
48
+ ```bash
49
+ docker build -t grocy-mcp .
50
+ docker run --rm -i \
51
+ -e GROCY_URL=https://grocy.example.com \
52
+ -e GROCY_KEY=your-api-key \
53
+ grocy-mcp
54
+ ```
55
+
56
+ ### From source
57
+
58
+ ```bash
59
+ git clone https://github.com/margosmark/grocy-mcp-server.git
60
+ cd grocy-mcp-server
61
+ python3 -m venv .venv && . .venv/bin/activate
62
+ pip install -e .
63
+ grocy-mcp-server
64
+ ```
65
+
66
+ ## Configuration
67
+
68
+ | Variable | Required | Description |
69
+ |---|---|---|
70
+ | `GROCY_URL` | yes | Base URL of your Grocy instance, no trailing slash needed |
71
+ | `GROCY_KEY` | yes | Grocy API key — Settings → Manage API keys → Add |
72
+
73
+ The key is sent as the `GROCY-API-KEY` header. Use a dedicated key so you can
74
+ revoke it without disturbing anything else.
75
+
76
+ ## Client setup
77
+
78
+ **Claude Desktop / Cursor / any MCP client (stdio):**
79
+
80
+ After `pip install grocy-mcp-server`, point the client at the console script:
81
+
82
+ ```json
83
+ {
84
+ "mcpServers": {
85
+ "grocy": {
86
+ "command": "grocy-mcp-server",
87
+ "env": {
88
+ "GROCY_URL": "https://grocy.example.com",
89
+ "GROCY_KEY": "your-api-key"
90
+ }
91
+ }
92
+ }
93
+ }
94
+ ```
95
+
96
+ Running from a checkout instead:
97
+
98
+ ```json
99
+ {
100
+ "mcpServers": {
101
+ "grocy": {
102
+ "command": "python3",
103
+ "args": ["-m", "grocy_mcp_server"],
104
+ "env": {
105
+ "GROCY_URL": "https://grocy.example.com",
106
+ "GROCY_KEY": "your-api-key"
107
+ }
108
+ }
109
+ }
110
+ }
111
+ ```
112
+
113
+ ## Tools
114
+
115
+ ### Stock
116
+ - `grocy_get_stock` — everything in stock with quantities, locations and due dates
117
+ - `grocy_get_stock_volatile` — overdue / due soon / expired / missing, grouped
118
+ - `grocy_get_product_stock` — stock detail for one product
119
+ - `grocy_add_stock` — add stock (amount, location, optional best-before)
120
+ - `grocy_consume_stock` — consume stock
121
+ - `grocy_transfer_stock` — move stock between locations
122
+ - `grocy_set_stock` — inventory correction (overwrites the count)
123
+ - `grocy_open_stock` — mark items as opened
124
+
125
+ ### Products
126
+ - `grocy_list_products` — list or search by name
127
+ - `grocy_get_product` — full product record
128
+ - `grocy_create_product` — create a product
129
+ - `grocy_delete_product` — delete a product *(destructive)*
130
+
131
+ ### Shopping list
132
+ - `grocy_get_shopping_list`
133
+ - `grocy_add_to_shopping_list`
134
+ - `grocy_add_note_to_shopping_list` — free text, no product needed
135
+ - `grocy_remove_from_shopping_list`
136
+ - `grocy_clear_shopping_list` *(destructive)*
137
+ - `grocy_add_missing_to_shopping_list` — everything below minimum stock
138
+
139
+ ### Lookups
140
+ `grocy_list_locations`, `grocy_list_product_groups`,
141
+ `grocy_list_quantity_units`, `grocy_list_shopping_locations`,
142
+ `grocy_list_chores`, `grocy_list_grocy_recipes`, `grocy_get_system_info`
143
+
144
+ ### Recipes
145
+ - `grocy_add_recipe_to_shopping_list` — add a recipe's missing ingredients
146
+
147
+ IDs are instance-specific. Every tool that takes an ID has a matching list tool;
148
+ resolve IDs at call time rather than hardcoding them.
149
+
150
+ ## Notes and limitations
151
+
152
+ - Recipes are read-only and basic — Grocy's recipe API is thin. Use a dedicated
153
+ recipe server if you need full recipe management.
154
+ - `grocy_set_stock` performs an inventory correction and overwrites the current
155
+ amount. Prefer `grocy_add_stock` / `grocy_consume_stock` for normal changes.
156
+ - Tested against Grocy 4.7.1. Older 3.x instances may differ in the volatile
157
+ stock response shape; both the 4.x object shape and a flat list are handled.
158
+
159
+ ## License
160
+
161
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,6 @@
1
+ """Grocy MCP server — Model Context Protocol access to a Grocy instance."""
2
+
3
+ from .server import mcp
4
+
5
+ __all__ = ["mcp"]
6
+ __version__ = "1.0.0"
@@ -0,0 +1,6 @@
1
+ """Allow `python -m grocy_mcp_server`."""
2
+
3
+ from .server import main
4
+
5
+ if __name__ == "__main__":
6
+ main()
File without changes