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

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.

print_text

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

print_image

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

print_from_url

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

print_from_html

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

get_print_status

Check the status of a submitted print job.

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.

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