Metadata-Version: 2.4
Name: grocy-mcp
Version: 0.1.0
Summary: MCP server and CLI for Grocy - control stock, shopping lists, recipes and chores via AI agents
Project-URL: Homepage, https://github.com/moustafattia/grocy-mcp
Project-URL: Repository, https://github.com/moustafattia/grocy-mcp
Project-URL: Issues, https://github.com/moustafattia/grocy-mcp/issues
Author: Moustafa Attia
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,cli,grocy,home-automation,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# grocy-mcp

MCP server and CLI for Grocy — control stock, shopping lists, recipes and chores via AI agents.

## Features

- **30 MCP tools** covering stock, shopping lists, recipes, chores, and system management
- **Full CLI** with subcommand groups mirroring every MCP tool
- **Name-based lookups** — pass product/recipe/chore names instead of numeric IDs
- **Dual transport** — stdio (for Claude Desktop / Claude Code) and streamable-http
- **Grocy v4.4.1+** compatible

## Installation

```bash
pip install grocy-mcp
```

Run without installing using `uvx`:

```bash
uvx grocy-mcp --transport stdio
```

## Configuration

grocy-mcp reads configuration from (in priority order):

1. CLI flags / environment variables
2. TOML config file

### Environment variables

```bash
export GROCY_URL="https://grocy.example.com"
export GROCY_API_KEY="your-api-key-here"
```

### TOML config file

Create `~/.config/grocy-mcp/config.toml` (Linux/macOS) or the platform equivalent:

```toml
[grocy]
url = "https://grocy.example.com"
api_key = "your-api-key-here"
```

## Usage

### MCP server — stdio (Claude Desktop / Claude Code)

```bash
grocy-mcp --transport stdio
```

### MCP server — streamable-http

```bash
grocy-mcp --transport streamable-http --port 8000
```

### Claude Code configuration

Add to your `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "grocy": {
      "command": "grocy-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "GROCY_URL": "https://grocy.example.com",
        "GROCY_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### CLI examples

```bash
# Stock
grocy stock overview
grocy stock expiring
grocy stock add Milk 2
grocy stock consume "Oat Milk" 1
grocy stock search milk
grocy stock barcode 5000112637922

# Shopping list
grocy shopping view
grocy shopping add Butter --amount 3
grocy shopping clear

# Recipes
grocy recipes list
grocy recipes details "Spaghetti Bolognese"
grocy recipes fulfillment "Spaghetti Bolognese"
grocy recipes consume "Spaghetti Bolognese"
grocy recipes add-to-shopping "Spaghetti Bolognese"

# Chores
grocy chores list
grocy chores overdue
grocy chores execute "Vacuum living room"
grocy chores undo "Vacuum living room"

# System
grocy system info
grocy entity list products
grocy entity manage products create --data '{"name": "Oat Milk"}'
```

## Development

```bash
git clone https://github.com/moustafattia/grocy-mcp
cd grocy-mcp
pip install -e ".[dev]"
pytest -v
```

## License

MIT
