Giftful MCP

A local Model Context Protocol server for logging in to Giftful and managing lists and wishes programmatically.

What it supports

• Persistent login with automatic access-token refresh

• Native credential-vault storage on macOS, Windows, and Linux

• Browser-based authentication for the sign-in methods offered by Giftful

• List, inspect, create, patch, and soft-delete lists

• Navigate accessible lists from followed friends, followers, and following

• List, add, patch, reorder, and delete wishes

• Claim and unclaim wishes on friends' lists

• Add a product URL and let Giftful retrieve its title, price, image, and description

• Create, reorder, and delete list categories

• Multiple accounts through named profiles

The password is used only for the login request and is never persisted. Only Giftful's refresh token and basic user metadata are stored. Short-lived access tokens remain in memory.

Authentication is CLI-only. The MCP server never accepts a Giftful password as a tool argument, so passwords do not enter model context or tool transcripts. When login is required, giftful_auth_status returns the appropriate terminal commands.

Related MCP server: Credential Manager MCP Server

Requirements

• Node.js 20 or newer

• A Giftful account

• Chrome, Edge, Brave, or Chromium for browser-based authentication

Install and build

npm install
npm run check

Everything required to build the server is in this project directory. Authentication data is stored separately and is never committed to the repository.

Log in securely

The recommended flow works with whichever sign-in method Giftful presents in the browser:

npm run auth -- login-browser

This opens Giftful in a temporary browser profile. Complete the normal login there using Apple or another available provider. The CLI reads only the resulting Giftful refresh credential, validates it with Giftful, saves it in your system credential vault, closes the browser, and deletes the temporary profile. It never receives your identity-provider password or verification codes. login-apple remains available as a compatibility alias.

The browser is discovered automatically. If needed, point to it explicitly with GIFTFUL_BROWSER_EXECUTABLE=/absolute/path/to/browser; the default login timeout is ten minutes and can be changed with GIFTFUL_BROWSER_LOGIN_TIMEOUT_MS.

For an email/password account, the recommended flow prompts for the password without echoing it:

npm run auth -- login YOUR_GIFTFUL_EMAIL

Confirm the saved session and exercise token refresh:

npm run auth -- status --validate

Log out and remove the persisted session:

npm run auth -- logout

For non-interactive automation, provide the password for that process only. It is removed from the process environment before login and is not saved:

GIFTFUL_PASSWORD='...' npm run auth -- login YOUR_GIFTFUL_EMAIL

Avoid putting GIFTFUL_PASSWORD in a long-lived shell profile or MCP configuration.

Connect it to Codex

Build first, then register the local stdio server using an absolute path:

codex mcp add giftful -- node /ABSOLUTE/PATH/TO/giftful-mcp/dist/index.js

Restart Codex or begin a new thread after adding it. Check registration with:

codex mcp get giftful

To use a named account profile:

codex mcp add giftful-personal \
  --env GIFTFUL_PROFILE=personal \
  -- node /ABSOLUTE/PATH/TO/giftful-mcp/dist/index.js

Run the login command with the same profile:

GIFTFUL_PROFILE=personal npm run auth -- login-browser
# or, for a password account:
GIFTFUL_PROFILE=personal npm run auth -- login YOUR_GIFTFUL_EMAIL

The equivalent generic MCP client configuration is:

{
  "mcpServers": {
    "giftful": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/giftful-mcp/dist/index.js"]
    }
  }
}

Tools

Examples of natural requests after connecting:

• “Show my Giftful lists.”

• “Show the lists belonging to people I follow.”

• “List the people I follow, then show Alice's available wishes.”

• “Reserve wish 12345 for me.”

• “Add this URL to my Christmas list and mark it most desired.”

• “Rename my christmas-2026 list and make link viewing private.”

• “Change wish 12345 to quantity 2.”

• “Move wish 12345 to the top of my birthday list.”

• “Put the Books category before Games.”

Giftful stores one list-wide relative order for wishes and a separate order for categories. When wishes are grouped for display, category order takes precedence; wishes inside each category retain their relative list-wide order. giftful_reorder_wish moves one wish after another (or to the global beginning), while giftful_reorder_categories accepts the complete category ID order.

Claiming is Giftful's reservation mechanism: it tells other Giftful users that the item is being handled. It does not place an order, charge a payment method, or buy anything from the linked retailer. Claim and unclaim both require confirm=true. The social tools are intentionally read-only; this MCP cannot find, follow, unfollow, accept, decline, remove, or otherwise modify social relationships.

Authentication storage

The default GIFTFUL_AUTH_STORAGE=auto uses the operating system's protected credential vault:

• macOS: Keychain item under service com.giftful-mcp.session

• Windows: Credential Manager

• Linux: Secret Service (normally backed by GNOME Keyring or KDE Wallet)

Overrides:

GIFTFUL_AUTH_STORAGE=system
GIFTFUL_AUTH_STORAGE=file
GIFTFUL_AUTH_FILE=/safe/absolute/path/session.json
GIFTFUL_PROFILE=work

System storage is the recommended cross-platform choice. On a headless Linux machine without Secret Service, opt into file storage explicitly. Its live refresh token is plaintext protected by filesystem permissions; the directory is mode 0700 and the file mode 0600. Keep it outside repositories and untrusted backups.

Development

npm run dev        # start stdio server from TypeScript
npm run typecheck
npm test
npm run build
npm run check:live-schema  # validates operations against Giftful; does not log in or write data
npm run check      # all of the above verification except dev

Tests mock Giftful login, refresh, social, and claim responses; they never require or mutate a real account. A live account smoke test is intentionally left to the owner because create/edit/delete and claim operations affect real lists.

Compatibility

This is an independent community project and is not affiliated with or endorsed by Giftful. Changes to Giftful may occasionally require a corresponding update here.

If Giftful changes its schema or authentication flow, errors are surfaced without deleting a valid saved session for ordinary network failures; sessions are cleared only when Giftful explicitly rejects the refresh credential.

License

MIT © 2026 Matthew Pulsipher.