huckleberry-mcp

Log baby events in Huckleberry by talking to the Claude or ChatGPT app. For example:

• "She fell asleep 10 minutes ago."

• "Starting a feed on the left." … "Switch sides." … "Done."

• "Wet and dirty diaper, yellow and runny."

• "Bottle, 4 ounces of formula at 2:30."

• "When did she last eat?"

This project is a small web server that you run on Fly.io. The Claude or ChatGPT app calls the server, and the server reads and writes your Huckleberry log. The standard that connects the AI app to the server is called MCP (Model Context Protocol).

Unofficial. The server uses py-huckleberry-api, a reverse-engineered client. Huckleberry Labs does not support it. It can stop working when Huckleberry changes its app.

Contents

• How it works

• What you need

• Step 1. Choose your values

• Step 2. Create a GitHub OAuth app

• Step 3. Create the Fly app

• Step 4. Add the secrets

• Step 5. Check the server

• Step 6. Connect Claude

• Step 7. Connect ChatGPT (optional)

• Step 8. Use it

• Troubleshooting

• Update the server

• Tools

• Settings reference

• Security

• Run locally and develop

• Limits

Related MCP server: babybuddy-mcp

How it works

You speak ──► Claude / ChatGPT app ──► https://YOUR-APP.fly.dev/mcp ──► Huckleberry
                                         │
                                         ├─ Check 1: GitHub sign-in
                                         └─ Check 2: your GitHub user id is on the allowlist

• You speak to the app on your phone. The app turns your words into a tool call, for example log_diaper(kind="both", color="yellow").

• Claude's or ChatGPT's servers send that call to your Fly server. Your phone does not connect to the Fly server directly.

• The server signs in to Huckleberry with your Huckleberry email and password, and then saves the event.

• Only you can use the server. Each request must come from a GitHub sign-in, and the GitHub account must be on your allowlist.

What you need

Time needed: about 30 minutes.

Step 1. Choose your values

Fill in this table before you start. Every later step uses these values.

GitHub user id. Open https://api.github.com/users/YOUR-GITHUB-LOGIN in a browser. Copy the number next to "id". Do not use your login name, because someone else can take a login after you rename yours. The number never changes.

Timezone. Use the IANA name for your home city. The server uses it to turn "2:30pm" into the correct moment. It is not related to the region.

For other places, see the "TZ identifier" column in the list of tz database time zones.

Region. Use ord (Chicago). The calls come from Claude's and ChatGPT's servers in the US, and Huckleberry's backend is most likely in the US, so a central US region keeps both connections short. This is true even if you live outside the US. Fly suggests a region near your own location, and a VPN can make it suggest another country. Change it to ord. Any US region also works.

Step 2. Create a GitHub OAuth app

The server uses this OAuth app to let you sign in with GitHub.

1. Open https://github.com/settings/developers.

2. Click OAuth Apps, then click New OAuth App.

3. Fill in the form:

   Field	Value
   Application name	Any name, for example Huckleberry MCP
   Homepage URL	Your App URL
   Application description	Leave empty
   Authorization callback URL	Your Callback URL. It must match exactly, with https and no / at the end.
   Enable Device Flow	Leave off

4. Click Register application.

5. Copy the Client ID.

6. Click Generate a new client secret. Copy the secret now. GitHub shows it only once.

Keep the client ID and the secret for Step 4. You can change the URLs later on the same page.

Step 3. Create the Fly app

Use the Fly web page (A) or the command line (B). Both read the fly.toml file in this repository.

A. Fly web page

1. In the Fly dashboard, start a new app from GitHub (https://fly.io/launch), and pick your copy of this repository.

2. Fill in the form:

   Field	Value	Why
   App name	Your App name	Sets your App URL.
   Region	ord - Chicago, Illinois (US)	See Step 1.
   Internal port	8000	The server listens on port 8000. Fly can show 8080 by default. With 8080, Fly cannot reach the server.
   CPU	shared-cpu-1x	Enough for one family.
   Memory	512MB	The server uses about 115 MB idle and more during Huckleberry calls. 256 MB can run out.
   Environment variables	The three values below	Settings that are not secret.
   Database / Managed Postgres	None	The server does not use a database.
   Working directory	Leave empty
   Config path	Leave empty

   Environment variables:

   HUCKLEBERRY_TIMEZONE     = your Timezone, for example America/Los_Angeles
   PUBLIC_BASE_URL          = your App URL, for example https://huckleberry-mcp-abc123.fly.dev
   ALLOWED_GITHUB_USER_IDS  = your GitHub user id, for example 1234567

   Do not put passwords here. Plain environment variables are visible in the app settings. Step 4 adds the passwords as encrypted secrets.

3. Click Deploy.

4. Fly opens a pull request in your repository that adds its own fly.toml with your app name. If the pull request is still open, merge it. Then run git pull on your computer.

B. Command line

1. Install flyctl: brew install flyctl (macOS) or curl -L https://fly.io/install.sh | sh (Linux). Then run fly auth login.

2. In fly.toml, set app to your App name and primary_region to your Region.

3. Create the app and its storage volume:

   fly apps create YOUR-APP-NAME
   fly volumes create huckleberry_data --size 1 --region ord --app YOUR-APP-NAME

4. Set the three values that are not secret:

   fly secrets set --stage --app YOUR-APP-NAME \
     HUCKLEBERRY_TIMEZONE=America/Los_Angeles \
     PUBLIC_BASE_URL=https://YOUR-APP-NAME.fly.dev \
     ALLOWED_GITHUB_USER_IDS=1234567

5. Do Step 4, and then run fly deploy.

What to expect

The first start fails. The log shows Configuration error: Missing required environment variables: ..., and the machine stops. This is correct. The server does not start until every required setting is present. Step 4 fixes it.

Step 4. Add the secrets

Add these four secrets. Fly encrypts secrets and does not show them again.

Web page: open https://fly.io/dashboard, click your app, click Secrets, and add each one. Saving the secrets restarts the app.

Command line: type each value when asked, so the password does not go into your shell history:

for name in HUCKLEBERRY_EMAIL HUCKLEBERRY_PASSWORD GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET; do
  printf '%s: ' "$name" >&2; IFS= read -rs value; echo >&2
  printf '%s=%s\n' "$name" "$value"
done | fly secrets import --app YOUR-APP-NAME

Step 5. Check the server

Run these three checks before you connect any app. Replace the URL with your App URL.

1. The server is up.

   curl -s -o /dev/null -w '%{http_code}\n' https://YOUR-APP-NAME.fly.dev/health

   Expected result: 200. The first call after the server has been idle can take up to about 20 seconds while the machine starts.

2. The server blocks strangers.

   curl -si -X POST https://YOUR-APP-NAME.fly.dev/mcp | grep -iE '^HTTP|^www-authenticate'

   Expected result: a 401 line and a www-authenticate: Bearer ... line. If you get anything else, stop and see Troubleshooting. Do not connect an app until you see 401.

3. The storage volume is attached. In the Fly dashboard, open your app and click Volumes. Expect one volume named huckleberry_data, attached to a machine. With the command line: fly volumes list --app YOUR-APP-NAME. Without the volume, the app forgets your sign-in each time the machine restarts.

Do not open the Callback URL in a browser to test it. It shows an error unless GitHub sends you there during sign-in. This is normal.

Step 6. Connect Claude

1. On a computer, open https://claude.ai.

2. Open Settings → Connectors, then click Add custom connector.

3. Enter a name, for example Huckleberry, and your Connector URL (it ends in /mcp). Click Add.

4. Click Connect. A consent page from your server opens. Approve it.

5. GitHub asks you to authorize your OAuth app. Sign in with the GitHub account whose id is in ALLOWED_GITHUB_USER_IDS, and click Authorize.

6. Claude shows the connector as connected.

7. Open the Claude app on your phone. The connector syncs from your account. In a chat, open the tools menu and turn on Huckleberry.

8. The first time Claude uses a tool, it asks for permission. Choose Always allow for each tool, so you do not have to tap for every event.

Step 7. Connect ChatGPT (optional)

ChatGPT adds custom MCP servers through developer mode, and its menu names change often. Look under Settings → Apps & Connectors → Advanced settings and turn on developer mode. Then create a connector with your Connector URL and OAuth authentication, and sign in with GitHub as in Step 6.

The server accepts ChatGPT's usual callback address. If ChatGPT reports a redirect error, find the rejected address in the Fly logs. Add it to the ALLOWED_REDIRECT_URIS secret, together with the default values listed in Settings reference.

Step 8. Use it

• Tap the microphone in the chat box and speak. The app turns your speech into text and sends it. Some app versions also let the full voice mode use connectors. Test it on your phone.

• Say the time when it was not "now": "at 2:30", "20 minutes ago".

• Say the child's name if the account has more than one child.

• Ask questions: "How long did she sleep last night?", "How many diapers today?"

• Claude confirms each saved event in one sentence. Check the Huckleberry app the first few times.

Troubleshooting

To read the server log: Fly dashboard → your app → Logs, or fly logs --app YOUR-APP-NAME.

Update the server

After you change the code or pull a new version:

git pull
fly deploy --app YOUR-APP-NAME

Tools

Each tool takes at (a clock time like 14:30 or 2:30pm, or an ISO time like 2026-11-04T14:30) or minutes_ago. With neither, the time is "now". A clock time later than now means yesterday.

Settings reference

The server does not start if a required setting is missing or invalid.

Security

• Sign-in. The server uses OAuth 2.1 with GitHub as the identity provider. A request without a valid token gets HTTP 401.

• Allowlist. Only the GitHub ids in ALLOWED_GITHUB_USER_IDS can see or call tools. Other GitHub users can sign in, but they get no tools.

• Least access. The server asks GitHub only for read:user, which is read access to your public profile.

• Callbacks. The server sends sign-in codes only to the addresses in ALLOWED_REDIRECT_URIS.

• Host check. The server answers only requests for the host in PUBLIC_BASE_URL. This blocks DNS-rebinding attacks.

• Secrets. Your Huckleberry password lives only in Fly's encrypted secret store. The repository and the Docker image contain no credentials.

• Logs. HTTP access logs are off, so sign-in codes do not reach the log.

• Container. The server runs as a regular user, not as root.

To remove access, delete the connector in Claude or ChatGPT. To block every existing sign-in at once, set a new JWT_SIGNING_KEY. If you never set JWT_SIGNING_KEY, generate a new client secret in the GitHub OAuth app and update GITHUB_CLIENT_SECRET instead.

Run locally and develop

Install uv and Python 3.14.

uv sync
uv run pytest                                      # tests use a fake Huckleberry API
uv run ruff check . && uv run ruff format --check .

To run the server on your computer, create a second GitHub OAuth app with the callback http://localhost:8000/auth/callback. Then:

cp .env.example .env    # fill it in; set PUBLIC_BASE_URL=http://localhost:8000
set -a; . ./.env; set +a
uv run huckleberry-mcp  # listens on 127.0.0.1:8000 only

With Docker, publish the port on your own computer only:

docker build -t huckleberry-mcp .
docker run --rm --env-file .env -p 127.0.0.1:8000:8000 -v huckleberry_data:/data huckleberry-mcp

Limits

• No tools yet for solids, potty, or live pump and activity timers.

• get_history covers at most 14 days per call.

• The Huckleberry connection is unofficial and can break without warning.

License

MIT. See LICENSE. Huckleberry is a trademark of Huckleberry Labs, Inc. This project is not affiliated with it.