mcp-familywall/README.md

# mcp-familywall

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

## Tools (v1.3.1)

### Wall & Activities

| Tool | Description |
|---|---|
| `get_wall_posts` | Get recent wall posts (text, author, likes, comments) |
| `create_wall_post` 🔒 | Create a new status post on the wall |
| `add_comment` 🔒 | Add a comment to a post |
| `like_post` 🔒 | Like or unlike a wall post/activity |
| `delete_wall_post` 🔒 | Permanently delete a wall post |

### Circles & Members

| Tool | Description |
|---|---|
| `get_circles` | List all family circles |
| `get_members` | List members of a circle (or all circles) |
| `create_circle` 🔒 | Create a new Family Wall circle |
| `update_circle` 🔒 | Rename a circle (primary circle protected) |
| `add_member_to_circle` 🔒 | Invite a person to a circle by e-mail |
| `delete_circle` 🔒 | Permanently delete a circle and all its content |

### Lists & Tasks

| Tool | Description |
|---|---|
| `get_lists` | List all task lists (emoji, color, circle; optional `scope` filter) |
| `get_tasks` | List tasks in a list (category, due date, assignees, recurrency, reminder) |
| `get_categories` | List categories for a list (locale-filtered; custom categories always shown) |
| `get_activities` | List recent wall activities (author resolved to display name) |
| `create_list` 🔒 | Create a task list (`SHOPPING_LIST`, `TODOS`, or `OTHER`; optional emoji, color, circle) |
| `update_list` 🔒 | Rename a list or change its emoji/color (partial update; system lists protected) |
| `delete_list` 🔒 | Permanently delete a list and all its tasks (system lists protected) |
| `create_category` 🔒 | Create a custom category (with optional icon) |
| `delete_category` 🔒 | Delete a custom category (system categories protected) |
| `create_task` 🔒 | Create a task (category, due date, assignees, reminder; use `"Äpfel (5x)"` for quantities) |
| `update_task` 🔒 | Update text, category, due date, assignees, recurrency, reminder, or move to a different list |
| `toggle_task` 🔒 | Mark a task complete or reopen it |
| `delete_task` 🔒 | Permanently delete a task |
| `clear_list` 🔒 | Bulk-delete all tasks in a list (optional `only_open=True` keeps completed tasks) |
| `like_post` 🔒 | Like a wall post/activity |

### Recipe Box

| Tool | Description |
|---|---|
| `get_recipe_categories` | List all recipe categories |
| `get_recipe_box` | List real recipes only (excludes free-text meal stubs) |
| `get_recipes` | List all recipe entries including stubs (compact summary) |
| `get_recipe` | Get a single recipe in full detail (ingredients, instructions, parsed ingredients) |
| `create_recipe` 🔒 | Create a new recipe (name, ingredients, instructions, prep/cook time, serves, url, categories) |
| `update_recipe` 🔒 | Update any field of a recipe (partial update; supports category_ids) |
| `delete_recipe` 🔒 | Permanently delete a recipe |

### Meal Planner (Premium)

| Tool | Description |
|---|---|
| `get_meal_plan` | Get meal plan entries for a date range (dish + meal entries, sorted by date + slot) |
| `add_recipe_to_meal_plan` 🔒 | Add a recipe-box recipe to a meal slot (BREAKFAST/LUNCH/SNACK/DINNER) |
| `add_meal_to_meal_plan` 🔒 | Add a free-text meal entry to a meal slot |
| `add_meal_note` 🔒 | Add a note and/or serving count to a meal slot |
| `delete_meal_plan_entry` 🔒 | Delete a meal plan entry (`dish/…` or `meal/…`) |

🔒 = requires user confirmation before calling

## 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](LICENSE) — © 2026 Marcus van Elst