mcp-familywall/README.md

mcp-familywall

MCP server for Family Wall -- read and manage your family's circles, lists, tasks, and recipes directly from Claude.

Features (v0.11.8)

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
• A Family Wall account

Installation

uv tool install mcp-familywall

Setup

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

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:

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

Verify

mcp-familywall check

Debug logging

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

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