Memobird MCP Server

MCP server for Memobird (咕咕机) thermal printer, based on memobirdsdk.

Prerequisites

• Node.js >= 18
• Memobird Access Key (from open.memobird.cn)
• Memobird device ID (double-click device to print it out)

Setup

npm install
npm run build

Configuration

Environment Variable	Required	Description
MEMOBIRD_AK	Yes	Access Key from open.memobird.cn
MEMOBIRD_DEVICE_ID	No	Device ID from bind_user, skip binding if set
MEMOBIRD_USER_ID	No	User ID from bind_user, skip binding if set

Usage

Via npx (Recommended)

No local clone needed. Add the following config to use the published npm package directly.

Claude Code — add to ~/.claude/settings.json:

First-time setup (only MEMOBIRD_AK needed, bind_user will be called automatically):

{
  "mcpServers": {
    "memobird": {
      "command": "npx",
      "args": ["-y", "memobirdmcp"],
      "env": {
        "MEMOBIRD_AK": "your-access-key"
      }
    }
  }
}

After first binding, add the returned userid and memobirdID to skip bind_user in future sessions:

{
  "mcpServers": {
    "memobird": {
      "command": "npx",
      "args": ["-y", "memobirdmcp"],
      "env": {
        "MEMOBIRD_AK": "your-access-key",
        "MEMOBIRD_DEVICE_ID": "your-device-id",
        "MEMOBIRD_USER_ID": "12345"
      }
    }
  }
}

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), same env format as above.

Via local build

If you prefer to run from source:

{
  "mcpServers": {
    "memobird": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "MEMOBIRD_AK": "your-access-key"
      }
    }
  }
}

Tools

bind_user

Bind a user identifier to a Memobird device. Must be called first if MEMOBIRD_DEVICE_ID and MEMOBIRD_USER_ID env vars are not set. Returns a userid and memobirdID — save them to env vars to skip this step in future sessions.

Parameter	Type	Required	Description
memobirdID	string	Yes	Device ID (double-click the device to obtain)
useridentifying	string	Yes	Your unique user identifier

print_text

Print text content to the bound device. Supports Chinese characters (auto GBK encoding).

Parameter	Type	Required	Description
text	string	Yes	Text content to print

print_image

Print a monochrome bitmap image to the bound device. Use convert_image first to convert JPG/PNG.

Parameter	Type	Required	Description
base64Image	string	Yes	Monochrome bitmap as Base64

print_from_url

Print content from a web URL to the bound device. Works best with static/server-rendered pages.

Parameter	Type	Required	Description
url	string	Yes	URL to print

print_from_html

Print content from HTML source to the bound device. Use inline CSS and absolute image URLs.

Parameter	Type	Required	Description
html	string	Yes	HTML source code

get_print_status

Check the status of a submitted print job.

Parameter	Type	Required	Description
printcontentid	string	Yes	Print content ID from a print tool response

Returns printflag: 1 if printed successfully, 0 if pending/failed.

convert_image

Convert a JPG/PNG image to monochrome bitmap format for printing. Use 384px width for best results.

Parameter	Type	Required	Description
base64Image	string	Yes	JPG or PNG image as Base64

Typical Workflow

First time

1. Call bind_user with your device ID and a user identifier
2. Save the returned userid and memobirdID to MEMOBIRD_USER_ID and MEMOBIRD_DEVICE_ID env vars in your MCP config
3. Use print tools as needed

Subsequent sessions (env vars set)

1. Use print_text / print_from_html / print_from_url directly (no binding needed)
2. For images: call convert_image first, then print_image with the result
3. Optionally call get_print_status to check if printing completed

License

ISC