memobirdMCP

# Memobird MCP Server MCP server for [Memobird (咕咕机)](http://www.memobird.cn) thermal printer, based on [memobirdsdk](https://www.npmjs.com/package/memobirdsdk). ## Prerequisites - Node.js >= 18 - Memobird Access Key (from [open.memobird.cn](http://open.memobird.cn)) - Memobird device ID (double-click device to print it out) ## Setup ```bash 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): ```json { "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: ```json { "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: ```json { "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