untappd-mcp 0.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "untappd-mcp",
+  "owner": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "metadata": {
+    "description": "MCP server for Untappd — beers, breweries, venues, check-ins, wishlists, and your friend feed",
+    "version": "0.0.0"
+  },
+  "plugins": [
+    {
+      "name": "untappd-mcp",
+      "displayName": "Untappd",
+      "source": "./",
+      "description": "MCP server for Untappd — search beers/breweries/venues, read profiles/check-ins/wishlists, and post check-ins, toasts, and comments",
+      "version": "0.0.0",
+      "author": {
+        "name": "Chris Hall"
+      },
+      "homepage": "https://github.com/chrischall/untappd-mcp",
+      "repository": "https://github.com/chrischall/untappd-mcp",
+      "license": "MIT",
+      "keywords": ["untappd", "beer", "breweries", "checkins", "mcp"],
+      "category": "lifestyle"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "untappd-mcp",
+  "displayName": "Untappd",
+  "version": "0.0.0",
+  "description": "MCP server for Untappd — search beers/breweries/venues, read check-ins and wishlists, and post check-ins, toasts, and comments",
+  "author": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "homepage": "https://github.com/chrischall/untappd-mcp",
+  "repository": "https://github.com/chrischall/untappd-mcp",
+  "license": "MIT",
+  "keywords": ["untappd", "beer", "breweries", "checkins", "mcp"],
+  "skills": "./SKILL.md",
+  "mcp": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "untappd": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"],
+      "env": {
+        "UNTAPPD_USERNAME": "${UNTAPPD_USERNAME}",
+        "UNTAPPD_PASSWORD": "${UNTAPPD_PASSWORD}",
+        "UNTAPPD_CLIENT_ID": "${UNTAPPD_CLIENT_ID}",
+        "UNTAPPD_CLIENT_SECRET": "${UNTAPPD_CLIENT_SECRET}"
+      }
+    }
+  }
+}

package/README.md

@@ -0,0 +1,75 @@
+# untappd-mcp
+
+An MCP server for [Untappd](https://untappd.com). It talks to Untappd's mobile
+(v4) API using your own account — search beers, breweries, and venues; read
+profiles, check-ins, wishlists, distinct beers, badges, friends, and your friend
+activity feed; and post check-ins, toasts, and comments.
+
+> Developed and maintained by AI (Claude Code). Use at your own discretion. This
+> is an unofficial client that uses Untappd's private mobile API; it is not
+> affiliated with or endorsed by Untappd.
+
+## How it works
+
+Untappd's iPad/iPhone app authenticates with a username/password **xauth** login
+(`POST https://api.untappd.com/v4/xauth`) that returns an access token, then
+calls the v4 API. This server reproduces that exactly:
+
+- Reads carry the token as an `access_token` query param.
+- Writes carry it as an `Authorization: Bearer` header (with the app's client
+  credentials in the query), matching the app's real requests.
+
+The token is fetched on demand, cached in memory, and refreshed automatically if
+it goes stale.
+
+## Configuration
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `UNTAPPD_USERNAME` | yes | Your Untappd username or login email. |
+| `UNTAPPD_PASSWORD` | yes | Your Untappd password (used only for the xauth login). |
+| `UNTAPPD_CLIENT_ID` | yes | The Untappd mobile app client id (see below). |
+| `UNTAPPD_CLIENT_SECRET` | yes | The Untappd mobile app client secret. |
+| `UNTAPPD_DEVICE_ID` | no | Stable device UUID the token is keyed to (a default is provided). |
+| `UNTAPPD_UTV` | no | API version param (default `4.0.0`). |
+| `UNTAPPD_USER_AGENT` | no | Override the User-Agent (default mimics the app). |
+
+Copy `.env.example` to `.env` and fill it in for local use.
+
+### Obtaining the client id / secret
+
+Untappd does not publish these; they live in the mobile app. Capture them from
+your own app's traffic with an HTTPS proxy:
+
+1. Install a proxy such as [mitmproxy](https://mitmproxy.org) and trust its CA
+   certificate on the device running the Untappd app.
+2. Point the device (or, on an Apple-silicon Mac running the iPad app, the Mac's
+   system HTTP/HTTPS proxy) at the proxy.
+3. Open Untappd and sign in. Find the `POST https://api.untappd.com/v4/xauth`
+   request — its **query string** contains `client_id` and `client_secret`.
+4. Put those into `UNTAPPD_CLIENT_ID` / `UNTAPPD_CLIENT_SECRET`.
+
+Keep these values private; do not commit them.
+
+## Tools
+
+Reads: `untappd_search_beer`, `untappd_beer_info`, `untappd_search_brewery`,
+`untappd_brewery_info`, `untappd_search_venue`, `untappd_venue_info`,
+`untappd_user_info`, `untappd_user_checkins`, `untappd_user_wishlist`,
+`untappd_user_beers`, `untappd_user_badges`, `untappd_user_friends`,
+`untappd_activity_feed`, `untappd_checkin_info`, `untappd_healthcheck`.
+
+Writes (confirm-gated — return a dry-run preview unless called with
+`confirm: true`): `untappd_toast`, `untappd_add_comment`, `untappd_checkin`.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: untappd-mcp
+description: Search Untappd beers, breweries, and venues; read user profiles, check-ins, wishlists, distinct beers, badges, friends, and your friend activity feed; and post check-ins, toasts, and comments to your own Untappd account. Use when the user asks about beer ratings, what a beer or brewery is like on Untappd, someone's Untappd check-ins or wishlist, or wants to log/toast/comment on a beer.
+---
+
+# Untappd MCP
+
+Talks to Untappd's mobile (v4) API using your own account. Logs in via the app's
+`xauth` endpoint (username + password → access token) and calls the same
+endpoints the iPad app uses.
+
+## Setup
+
+Set four environment variables (see the README for details):
+
+- `UNTAPPD_USERNAME`, `UNTAPPD_PASSWORD` — your Untappd login.
+- `UNTAPPD_CLIENT_ID`, `UNTAPPD_CLIENT_SECRET` — the Untappd mobile app client
+  credentials (obtained by intercepting the app's traffic; see README).
+
+Run `untappd_healthcheck` to confirm login works.
+
+## Read tools
+
+- `untappd_search_beer` / `untappd_beer_info` — find beers, then get full detail by bid.
+- `untappd_search_brewery` / `untappd_brewery_info` — breweries.
+- `untappd_search_venue` / `untappd_venue_info` — bars, breweries, restaurants.
+- `untappd_user_info` — a user's profile (omit `username` for your own).
+- `untappd_user_checkins` — recent check-ins (page with `max_id`).
+- `untappd_user_wishlist` — wishlist beers.
+- `untappd_user_beers` — distinct beers ever checked in.
+- `untappd_user_badges` / `untappd_user_friends`.
+- `untappd_activity_feed` — your friend feed (page with `max_id`).
+- `untappd_checkin_info` — full detail of one check-in.
+
+Most user tools default `username` to your configured account when omitted.
+
+## Write tools (confirm-gated — these post to your public account)
+
+Each returns a dry-run preview and makes NO network call unless called with
+`confirm: true`:
+
+- `untappd_toast` — toast/like a check-in (this endpoint is a toggle).
+- `untappd_add_comment` — comment on a check-in.
+- `untappd_checkin` — post a new beer check-in to your feed (needs a `bid` from
+  `untappd_search_beer`; optional `rating` 0–5 in 0.25 steps, `shout`, venue).
+
+Photo attachment and wishlist add/remove are not yet supported.