mcp-familywall/README.md

# mcp-familywall

MCP server for [Family Wall](https://www.familywall.com) -- read and manage your family's circles, lists, tasks, and recipes directly from Claude.

## Features (v0.11.7)

### Read

- `get_circles` -- list all family circles
- `get_members` -- list members of a circle (or all circles)
- `get_lists` -- list all task lists (includes `emoji`, `color`, `circle_id`; `null` when unset; list types: `SHOPPING_LIST`, `TODOS`, `OTHER`); without scope parameter returns lists from **all circles**; optional `scope` parameter filters by circle metaId or circle name
- `get_tasks` -- list tasks in a specific list (includes `category_id`, `due_date`, `assignee_ids`, `recurrency`, `rrule`, `reminder`)
- `get_categories` -- list categories for a list (locale-filtered; custom categories always included; `custom` flag marks user-created ones)
- `get_activities` -- list recent wall activities (author resolved to display name)
- `get_recipes` -- list all family recipes (compact summary: id, name, prep/cook time, serves)
- `get_recipe_box` -- list only real recipes from the recipe box (excludes stubs created for free-text meal entries)
- `get_recipe` -- get a single recipe in full detail (ingredients, instructions, ingredients_parsed, category_ids, etc.; ingredients_parsed generated from free-text field to avoid parser bugs)
- `get_recipe_categories` -- list all available recipe categories (always returns all 5 standard categories: Bei Kindern beliebt, Wirklich einfach, Nachspeisen, Schmeckt toll, Gemüse; plus any additional categories found in existing recipes)
- `get_meal_plan` -- get meal plan entries for a date range (Premium feature; merges dish and meal entries, sorted by date + type; fields: id, date, type, name, recipe_id, is_from_recipe_box, note, serves, can_update, can_delete)

### Write (with confirmation prompt)

- `create_task` -- create a new task in a list (supports `category_id`, `due_date`, `assignee_ids`); use `"Äpfel (5x)"` format for quantities
- `update_task` -- update text, description, category, due date, assignees, or move to a different list; supports `clear_due_date=True` to remove a due date
- `toggle_task` -- mark a task complete or reopen it
- `delete_task` -- permanently delete a task
- `clear_list` -- delete all tasks in a list in a single session (bulk delete; optional `only_open=True` to keep completed tasks)
- `create_list` -- create a new task list (`SHOPPING_LIST`, `TODOS`, or `OTHER`; optional `emoji`, `color`, and `circle_id` to target a specific circle)
- `update_list` -- rename a list or change its emoji/color (partial update — omitted fields unchanged; system lists are protected)
- `delete_list` -- permanently delete a list and all its tasks (system lists are protected)
- `create_category` -- create a custom category for a shopping list (with optional icon)
- `delete_category` -- delete a custom category (system categories are protected)
- `like_post` -- like a wall post/activity
- `create_recipe` -- create a new recipe (name, description, ingredients, instructions, prep/cook time, serves, url, category_ids); use `\n` to separate ingredient lines
- `update_recipe` -- update any field of an existing recipe (partial update — omitted fields unchanged; supports `category_ids` list to change categories)
- `delete_recipe` -- permanently delete a recipe (only own recipes)
- `add_recipe_to_meal_plan` -- add a recipe from the recipe box to the meal plan for a specific date and meal slot (BREAKFAST/LUNCH/SNACK/DINNER)
- `add_meal_to_meal_plan` -- add a free-text meal entry (no recipe) to the meal plan for a specific date and meal slot
- `add_meal_note` -- add a note and/or serving count to a meal plan slot (creates a `meal/` entry; at least one of `note` or `serves` required)
- `delete_meal_plan_entry` -- permanently delete a meal plan entry (works for both `dish/…` and `meal/…` entries)
- `create_circle` -- create a new Family Wall circle (group)
- `update_circle` -- rename a circle (server capitalises first letter; only name is changeable via API; primary circle is protected)
- `delete_circle` -- permanently delete a circle and all its content (primary circle is protected)
- `add_member_to_circle` -- invite a person to a circle by e-mail (for new Family Wall users only; existing accounts require in-app invitation)

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- A Family Wall account

## Installation

```bash
uv tool install mcp-familywall
```

## Setup

Run the interactive setup wizard once to store your credentials securely in the OS keyring:

```bash
mcp-familywall setup
```

This will:
1. Prompt for your Family Wall email and password
2. Verify the credentials against the API
3. Store them in the OS keyring
4. Print a Claude Desktop configuration snippet

## Claude Desktop configuration

Add the printed snippet to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "familywall": {
      "command": "uvx",
      "args": ["mcp-familywall", "serve"]
    }
  }
}
```

## Verify

```bash
mcp-familywall check
```

## Debug logging

Set `FW_DEBUG=1` to log full request/response bodies to stderr (passwords are masked):

```bash
FW_DEBUG=1 mcp-familywall check
```

## Credentials

Credentials are resolved in this order:

1. Environment variables `FW_EMAIL` and `FW_PASSWORD`
2. OS keyring (set by `mcp-familywall setup`)

## License

MIT