# mcp-familywall

MCP server for [Family Wall](https://www.familywall.com) -- 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](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