mcp-familywall/README.md

mcp-familywall

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

Features (v0.5.2)

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 and color; null when unset)
• get_tasks -- list tasks in a specific list (includes category_id, due_date, assignee_ids)
• 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)

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
• create_list -- create a new task list (SHOPPING_LIST or TODOS; optional emoji and color)
• 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

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