org.giftcardshop/mcp
Browse the giftcardshop catalog and buy gift cards with Lightning over MCP. No account, no signup.
Open source Open in the app JSON README (API)
About
Browse the giftcardshop catalog and buy gift cards with Lightning over MCP. No account, no signup.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- org.giftcardshop
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Last push
- 2026-06-16T17:41:02Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:52
- Updated
- 2026-08-29 04:01:52
- Origin id
org.giftcardshop/mcp
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
```bash
# 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):
```json
{
"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).