About giftcardshop
giftcardshop is an MCP server for AI agents to browse a gift-card catalog and place purchases using Lightning. Browsing works without credentials; checkout requires a shared secret and returns an invoice followed by a single-view code reveal link.
Key features
- 01Browse gift-card brands and products
- 02View product variants and denominations
- 03Create orders with a Lightning invoice
- 04Check payment status and reveal availability
Use cases
- 01Find gift cards in the catalog
- 02Inspect denominations before purchase
- 03Pay for a gift-card order with Lightning
- 04Check whether an order's reveal link is ready
MCP support
Exposes catalog, product, order-status and order-creation tools to MCP clients. Read tools use the public API without a key; `create_order` requires `GCS_INTERNAL_SECRET`.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @giftcardshop/mcpGCS_INTERNAL_SECRETSecret64-hex HMAC secret that enables create_order (Lightning checkout). Browsing tools work without it. Requested at https://giftcardshop.org/contact.GCS_API_BASEOverride the public API base. Defaults to https://api.giftcardshop.org.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
5Saved tool list · updated 3w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | |
| offset | integer | No | |
| country | string | No | ISO 3166-1 alpha-2 country code, e.g. US |
Details
From the project README@giftcardshop/mcp
MCP server that lets AI agents browse the giftcardshop catalog and buy gift cards with Lightning - no account, no signup. The agent pays a Lightning invoice and receives a single-view reveal link with the code.
Read tools work against the live public API with no key. create_order is
early access: it needs the shared GCS_INTERNAL_SECRET (request one at
https://giftcardshop.org/contact); without it the read tools still work and
create_order reports that it is not configured.
Tools
| Tool | Kind | Backed by |
|---|---|---|
list_brands | read | GET /v1/brands |
search_products | read | GET /v1/products |
get_product | read | GET /v1/products/:id (variants + denominations) |
get_order_status | read | GET /v1/orders/:id (payment state + reveal availability) |
create_order | write | POST /internal/agent-orders (HMAC) -> Lightning invoice |
Read tools pass the API JSON through verbatim. create_order returns
{ orderId, invoiceId, invoiceUrl, bolt11?, sats?, total, currency, expiresAt }.
Run
# read-only (browsing works, create_order reports "not configured")
npx @giftcardshop/mcp
# with checkout enabled
GCS_INTERNAL_SECRET=<64-hex> npx @giftcardshop/mcp
Claude Desktop / any MCP client (stdio):
{
"mcpServers": {
"giftcardshop": {
"command": "npx",
"args": ["-y", "@giftcardshop/mcp"],
"env": { "GCS_INTERNAL_SECRET": "<64-hex>" }
}
}
}
Config
| Env | Default | Purpose |
|---|---|---|
GCS_API_BASE | https://api.giftcardshop.org | public API base |
GCS_INTERNAL_SECRET | (unset) | 64-hex HMAC secret; enables create_order. Unset = read-only. |
Checkout (create_order)
create_order POSTs to POST /internal/agent-orders, HMAC-signed with
GCS_INTERNAL_SECRET (header x-internal-sig), and returns a Lightning
invoice. Pay it, then poll get_order_status for the single-view reveal
link. No Nostr identity and no partner account required.
Roadmap
- L402 (Lightning HTTP 402) so an agent pays per-call without a human step.
- A hosted remote MCP over HTTP, so there is nothing to install.
- A btcrecharge MCP for mobile top-ups (same shape).
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.