untappd-mcp

Check in a beer on Untappd

untappd_checkin

Destructive

Post a new beer check-in to your Untappd account, publishing it to your public feed. Add a rating, shout, venue, or photo, preview the exact fields, then confirm to publish.

Instructions

Post a NEW beer check-in to YOUR Untappd account — this publishes to your public feed. Provide the beer id (bid) from untappd_search_beer; optionally a rating (0–5 in 0.25 steps), a shout (comment), a venue via foursquare_id, and ONE photo (JPEG/PNG, max 15 MB) via exactly one of photo_path (a local file), photo_inline (base64, for a small photo) or photo_blob_key. On the hosted connector, use the slot flow: call untappd_upload_slots, PUT the photo with the returned curl, then pass its blobKey as photo_blob_key (a path cannot work there). The preview shows the exact fields and photo that will be posted. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Input Schema

Name	Required	Description
`bid`	Yes	Untappd beer id to check in (from untappd_search_beer)
`shout`	No	Optional shout / comment text for the check-in
`geolat`	No	Optional latitude of the check-in
`geolng`	No	Optional longitude of the check-in
`rating`	No	Rating 0–5 in 0.25 increments (omit for no rating)
`timezone`	No	The drinker's IANA timezone (e.g. America/New_York), which sets the check-in's local time. Defaults to UNTAPPD_TIMEZONE, else the server's own zone — which on a hosted connector is usually UTC, so pass it when you know where the user is.
`photo_path`	No	Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. It must be inside the photo directory (UNTAPPD_PHOTO_DIR, default ~/Downloads/untappd-mcp). Only use a file the user explicitly chose; the preview shows the resolved path and size for them to confirm. Local installs only — refused on the hosted connector (use photo_blob_key).
`confirmToken`	No	ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
`container_id`	No	Optional serving container id (e.g. 1 = draft, 2 = bottle, 3 = can)
`photo_inline`	No	Optional photo as base64: {filename, contentBase64, mimeType?}, JPEG or PNG, max 15 MB — it is published publicly. Works on any deployment; for anything but a small photo prefer the upload slot flow (photo_blob_key). Only use a photo the user explicitly chose.
`foursquare_id`	No	Optional Foursquare venue id to tag the check-in location
`photo_blob_key`	No	Optional blobKey of a photo PUT to a slot from untappd_upload_slots (hosted connector) — it is published publicly. Deleted from the upload store once the check-in and its photo succeed; kept if they fail.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.7.0Nov 7, 2026

addedInput schema / properties / photo_blob_key

Added value: +{
+  "description": "Optional blobKey of a photo PUT to a slot from untappd_upload_slots (hosted connector) — it is published publicly. Deleted from the upload store once the check-in and its photo succeed; kept if they fail.",
+  "type": "string"
+}

addedInput schema / properties / photo_inline

Added value: +{
+  "description": "Optional photo as base64: {filename, contentBase64, mimeType?}, JPEG or PNG, max 15 MB — it is published publicly. Works on any deployment; for anything but a small photo prefer the upload slot flow (photo_blob_key). Only use a photo the user explicitly chose.",
+  "properties": {
+    "contentBase64": {
+      "description": "The file's bytes, standard base64 (line breaks and a \"data:<type>;base64,\" prefix are tolerated).",
+      "type": "string"
+    },
+    "filename": {
+      "description": "Filename the upstream will show — a bare name, no path, not starting with a dot. Its extension sets the MIME type when mimeType is omitted.",
+      "type": "string"
+    },
+    "mimeType": {
+      "description": "MIME type, e.g. \"image/jpeg\". Default: inferred from the filename extension.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "filename",
+    "contentBase64"
+  ],
+  "type": "object"
+}

changedInput schema / properties / photo_path / description

Previous value: -"Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. It must be inside the photo directory (UNTAPPD_PHOTO_DIR, default ~/Downloads/untappd-mcp). Only use a file the user explicitly chose; the preview shows the resolved path and size for them to confirm."New value: +"Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. It must be inside the photo directory (UNTAPPD_PHOTO_DIR, default ~/Downloads/untappd-mcp). Only use a file the user explicitly chose; the preview shows the resolved path and size for them to confirm. Local installs only — refused on the hosted connector (use photo_blob_key)."

Changed1 schema field changedv2.3.2Oct 16, 2026

changedInput schema / properties / photo_path / description

Previous value: -"Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. Only use a file the user explicitly chose; the preview shows the resolved path and size for them to confirm."New value: +"Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. It must be inside the photo directory (UNTAPPD_PHOTO_DIR, default ~/Downloads/untappd-mcp). Only use a file the user explicitly chose; the preview shows the resolved path and size for them to confirm."

Changed3 schema fields changedv2.2.1Sep 25, 2026

removedInput schema / properties / confirm

Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}

addedInput schema / properties / confirmToken

Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}

changedInput schema / properties / photo_path / description

Previous value: -"Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. Only use a file the user explicitly chose; the dry run shows the resolved path and size for them to confirm."New value: +"Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. Only use a file the user explicitly chose; the preview shows the resolved path and size for them to confirm."

Changed2 schema fields changedv2.1.3Sep 24, 2026

changedInput schema / properties / photo_path / description

Previous value: -"Optional path to a local JPEG/PNG photo to attach to the check-in"New value: +"Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. Only use a file the user explicitly chose; the dry run shows the resolved path and size for them to confirm."

addedInput schema / properties / timezone

Added value: +{
+  "description": "The drinker's IANA timezone (e.g. America/New_York), which sets the check-in's local time. Defaults to UNTAPPD_TIMEZONE, else the server's own zone — which on a hosted connector is usually UTC, so pass it when you know where the user is.",
+  "minLength": 1,
+  "type": "string"
+}

Changed1 schema field changedv2.0.0Sep 19, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedv1.0.0Jul 8, 2026

addedInput schema / properties / photo_path

Added value: +{
+  "description": "Optional path to a local JPEG/PNG photo to attach to the check-in",
+  "type": "string"
+}

First observedv0.0.0Jul 8, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructive/openWorld/non-idempotent, and the description adds what the annotations cannot: the check-in is published publicly, a preview is shown before posting, the call may not proceed without explicit confirmation, and the uploaded blob is deleted on success but kept on failure. That is real behavioral context beyond the structured hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and the publish-to-feed consequence, and every clause carries operational weight. It is dense with parenthetical detail in a single block, which slightly hurts scanability and partially restates the confirmToken schema text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter, nested-photo, publicly-destructive mutation with no output schema, the description covers everything an agent needs: source of the id, mutually exclusive photo channels, deployment restrictions, confirmation flow, and the preview. Nothing material is left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be a 3, but the description adds cross-parameter semantics the schema does not encode: only ONE photo, supplied via exactly one of photo_path/photo_inline/photo_blob_key, with the deployment-dependent constraint on photo_path. It also clarifies the practical default behavior of timezone on a hosted connector.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Post a NEW beer check-in") plus scope ("to YOUR Untappd account — this publishes to your public feed"). This clearly separates it from read-side siblings like untappd_checkin_info and from untappd_delete_checkin.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: bid comes from untappd_search_beer, photos on a hosted connector go through untappd_upload_slots then a PUT then photo_blob_key, and local paths are refused there. It also spells out the confirmation protocol (client prompt vs preview + confirmToken) rather than leaving it to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Check in a beer on Untappd

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools