{"_id":"@ambosstech/magma-mcp","_rev":"2-78d0376576923a040327fc67133ae20b","name":"@ambosstech/magma-mcp","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@ambosstech/magma-mcp","version":"0.0.1","keywords":["mcp","model-context-protocol","lightning-network","bitcoin","amboss","magma","liquidity","lightning","ln","btc"],"author":{"name":"Amboss Technologies"},"license":"MIT","_id":"@ambosstech/magma-mcp@0.0.1","maintainers":[{"name":"ambossbot","email":"external-npm@amboss.tech"}],"homepage":"https://github.com/amboss-tech/magma-mcp#readme","bugs":{"url":"https://github.com/amboss-tech/magma-mcp/issues"},"bin":{"magma-mcp":"dist/index.js"},"dist":{"shasum":"ffca95175c736f50405372b8b0a320023cdacd65","tarball":"https://registry.npmjs.org/@ambosstech/magma-mcp/-/magma-mcp-0.0.1.tgz","fileCount":35,"integrity":"sha512-CXmF5dI8+cwDh+Q2amPEjvzoeHn6/lO3zK1fbC+PYa+IIXsyen13Dsf7INW9adeSnFoKfabi9r1jGiiLuoo9Hg==","signatures":[{"sig":"MEQCIEG7s90gsNvMGZY5lu3QSik2zf36Y60m68gcpbomi1GVAiBB7F4h8TqsDmntipIkHdUMJHqZ6ol4Ql5etlWkQuuiGw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":85918},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"9019d9d6df25e53af81cbd39128ff8422511dc49","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc && chmod +x dist/index.js","start":"node dist/index.js","inspector":"npx @modelcontextprotocol/inspector dist/index.js","typecheck":"tsc --noEmit","preversion":"npm run typecheck && npm test","test:watch":"vitest","postversion":"git push && git push --tags","test:coverage":"vitest run --coverage","prepublishOnly":"npm run typecheck && npm test && npm run build"},"_npmUser":{"name":"ambossbot","email":"external-npm@amboss.tech"},"repository":{"url":"git+https://github.com/amboss-tech/magma-mcp.git","type":"git"},"_npmVersion":"10.2.4","description":"MCP server to buy Lightning Network liquidity through Amboss Magma","directories":{},"_nodeVersion":"20.11.1","dependencies":{"zod":"^4.3.6","dotenv":"16.4.5","graphql":"^16.12.0","graphql-request":"^7.4.0","zod-to-json-schema":"^3.25.1","@modelcontextprotocol/sdk":"^1.25.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.5.2","devDependencies":{"tsx":"^4.21.0","vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^25.2.0","@vitest/coverage-v8":"^4.0.18"},"_npmOperationalInternal":{"tmp":"tmp/magma-mcp_0.0.1_1770168543631_0.29965222252951373","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@ambosstech/magma-mcp","version":"0.0.2","description":"Node.js client library and MCP server to buy Lightning Network liquidity through Amboss Magma","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"magma-mcp":"dist/server.js"},"repository":{"type":"git","url":"git+https://github.com/AmbossTech/magma-mcp.git"},"bugs":{"url":"https://github.com/AmbossTech/magma-mcp/issues"},"homepage":"https://github.com/AmbossTech/magma-mcp#readme","scripts":{"build":"tsc && chmod +x dist/server.js","dev":"tsx src/server.ts","start":"node dist/server.js","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","typecheck":"tsc --noEmit","inspector":"npx @modelcontextprotocol/inspector dist/server.js","prepublishOnly":"npm run typecheck && npm test && npm run build","preversion":"npm run typecheck && npm test","postversion":"git push && git push --tags"},"keywords":["mcp","model-context-protocol","lightning-network","bitcoin","amboss","magma","liquidity","lightning","ln","btc","client","api","nodejs"],"author":{"name":"Amboss Technologies"},"license":"MIT","packageManager":"pnpm@10.5.2","publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.25.3","dotenv":"16.4.5","graphql":"^16.12.0","graphql-request":"^7.4.0","zod":"^4.3.6","zod-to-json-schema":"^3.25.1"},"devDependencies":{"@types/node":"^25.2.0","@vitest/coverage-v8":"^4.0.18","tsx":"^4.21.0","typescript":"^5.9.3","vitest":"^4.0.18"},"gitHead":"e8c039f42fc2d727cc068993c97071e8b07e9d6b","_id":"@ambosstech/magma-mcp@0.0.2","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-R5XuBrLZ3B7YA0KGBg30PvWzDFWB3aj2hjLdC9CB7hrcK4GdN1FtcUo8Ij2IvmBmwoSAi/HxmZaMOekNUUTORA==","shasum":"7f9c229d9a144c0a5c2f399a3cedab096e18cd5c","tarball":"https://registry.npmjs.org/@ambosstech/magma-mcp/-/magma-mcp-0.0.2.tgz","fileCount":47,"unpackedSize":109944,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ambosstech%2fmagma-mcp@0.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCY05F1u8/QZ9VTYSqK4hn/EoWH+uDisYpGFa7oYjtrFgIgIxmRU9J6ufe1kR+yhbre6K+4jWpZGV+6W5vg7fQG8+M="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:b96c1454-552f-4f0b-88a2-e4c4063f67e8"}},"directories":{},"maintainers":[{"name":"ambossbot","email":"external-npm@amboss.tech"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/magma-mcp_0.0.2_1770196965886_0.9619553000369505"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-04T01:29:03.548Z","modified":"2026-02-04T09:22:46.342Z","0.0.1":"2026-02-04T01:29:03.779Z","0.0.2":"2026-02-04T09:22:46.028Z"},"bugs":{"url":"https://github.com/AmbossTech/magma-mcp/issues"},"author":{"name":"Amboss Technologies"},"license":"MIT","homepage":"https://github.com/AmbossTech/magma-mcp#readme","keywords":["mcp","model-context-protocol","lightning-network","bitcoin","amboss","magma","liquidity","lightning","ln","btc","client","api","nodejs"],"repository":{"type":"git","url":"git+https://github.com/AmbossTech/magma-mcp.git"},"description":"Node.js client library and MCP server to buy Lightning Network liquidity through Amboss Magma","maintainers":[{"name":"ambossbot","email":"external-npm@amboss.tech"}],"readme":"# Magma MCP\n\nNode.js client library and Model Context Protocol (MCP) server for buying Lightning Network liquidity via [Amboss Magma](https://magma.amboss.tech/).\n\n## Overview\n\nThis package provides two ways to interact with the Amboss Magma API:\n\n1. **Node.js Client Library**: Programmatically buy Lightning liquidity from your Node.js applications\n2. **MCP Server**: Enable AI assistants like Claude to purchase inbound Lightning Network liquidity for your node\n\nBoth interfaces provide a seamless way to increase your node's receiving capacity through the Amboss Magma API.\n\n## Features\n\n- **Buy Lightning Liquidity**: Purchase inbound liquidity for your Lightning node\n- **Anonymous Access**: Works without an API key - the Magma API creates temporary accounts automatically\n- **Optional Authentication**: Use your Amboss account API key for personalized access\n- **Input Validation**: Comprehensive validation of all parameters\n- **Error Handling**: Clear, user-friendly error messages\n- **Retry Logic**: Automatic retry for transient network failures\n\n## Prerequisites\n\n- Node.js >= 18.0.0\n- pnpm (or npm/yarn)\n- A Lightning Network node with accessible connection URI\n- (Optional) Amboss Magma API key ([Get one here](https://account.amboss.tech/settings/api-keys))\n\n## Installation\n\n### From npm (Recommended)\n\n```bash\nnpm install -g @ambosstech/magma-mcp\n```\n\nOr with pnpm:\n\n```bash\npnpm add -g @ambosstech/magma-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/AmbossTech/magma-mcp.git\ncd magma-mcp\npnpm install\npnpm build\n```\n\n### Configure environment variables (Optional)\n\nThe Magma API supports **anonymous access** - you can use the server without an API key! The API will automatically create temporary accounts with session keys.\n\nIf you want to use your existing Amboss account, create a `.env` file:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and add your Magma API key:\n\n```env\nMAGMA_API_KEY=your_api_key_here\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `MAGMA_API_KEY` | No | - | Your Amboss Magma API key (optional - supports anonymous access) |\n| `MAGMA_GRAPHQL_ENDPOINT` | No | `https://magma.amboss.tech/graphql` | Magma GraphQL endpoint |\n| `LOG_LEVEL` | No | `info` | Logging level (debug, info, warn, error) |\n\n### Claude Desktop Integration\n\nAdd the following configuration to your Claude Desktop config file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n**Option 1: Using npm package (anonymous access)**\n```json\n{\n  \"mcpServers\": {\n    \"magma\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ambosstech/magma-mcp\"]\n    }\n  }\n}\n```\n\n**Option 2: Using npm package (with API key)**\n```json\n{\n  \"mcpServers\": {\n    \"magma\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ambosstech/magma-mcp\"],\n      \"env\": {\n        \"MAGMA_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n**Option 3: From source (development)**\n```json\n{\n  \"mcpServers\": {\n    \"magma\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/magma-mcp/dist/server.js\"],\n      \"env\": {\n        \"MAGMA_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\nAfter adding the configuration:\n1. Save the file\n2. Restart Claude Desktop\n3. The Magma MCP server will be available\n\n## Usage\n\nOnce configured, you can use natural language with Claude to buy Lightning liquidity:\n\n### Example Prompts\n\n**Basic purchase:**\n```\nBuy $10 of Lightning liquidity for my node at 024ae5a5f0b0185...@12.34.56.78:9735\n```\n\n**With options:**\n```\nBuy $50 of Lightning liquidity for 024ae5a5f0b0185...@12.34.56.78:9735\nusing only Rails cluster nodes\n```\n\n**Private channel:**\n```\nBuy $25 of private channel liquidity for my node 024ae5a5f0b0185...@12.34.56.78:9735\n```\n\n### Tool: `buy_lightning_liquidity`\n\n**Parameters:**\n\n- `connection_uri` (required): Your node's connection string (either just pubkey or pubkey@host:port)\n  - Just pubkey: `024ae5a5f0b01850983009489ca89c85...`\n  - With socket: `024ae5a5f0b01850983009489ca89c85...@12.34.56.78:9735`\n- `usd_cents` (required): Dollar amount in cents (minimum 500 = $5.00)\n- `redirect_url` (optional): URL to redirect after payment\n- `private_channel` (optional): Create private channel (default: false)\n- `rails_cluster_only` (optional): Source only from Rails cluster (default: false)\n\n**Returns:**\n\n```json\n{\n  \"success\": true,\n  \"lightning_invoice\": \"lnbc10m1p3j8z9xpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypq...\"\n}\n```\n\nThe Lightning invoice can be paid using any Lightning wallet to complete the liquidity purchase.\n\n## Using as a Node.js Library\n\nIn addition to the MCP server, this package can be used as a Node.js client library to programmatically interact with the Amboss Magma API.\n\n### Installation\n\n```bash\nnpm install @ambosstech/magma-mcp\n```\n\n### Quick Start\n\n```typescript\nimport { MagmaClient } from '@ambosstech/magma-mcp';\n\n// Create client (anonymous access)\nconst client = new MagmaClient();\n\n// Or with API key\nconst client = new MagmaClient({\n  apiKey: process.env.MAGMA_API_KEY\n});\n\n// Buy liquidity\nconst invoice = await client.buyLiquidity({\n  connectionUri: '024ae5a5f0b01850983009489ca89c85...@12.34.56.78:9735',\n  usdCents: 1000  // $10.00\n});\n\nconsole.log('Pay this Lightning invoice:', invoice);\n```\n\n### API Reference\n\n#### `MagmaClient`\n\n**Constructor:**\n\n```typescript\nnew MagmaClient(config?: MagmaClientConfig)\n```\n\n**Config options:**\n- `apiKey?: string` - Your Amboss Magma API key (optional, supports anonymous access)\n- `endpoint?: string` - GraphQL endpoint (default: `https://magma.amboss.tech/graphql`)\n- `logLevel?: 'debug' | 'info' | 'error'` - Logging level (default: `error`)\n\n**Methods:**\n\n##### `buyLiquidity(options: BuyLiquidityOptions): Promise<string>`\n\nPurchase inbound Lightning Network liquidity for a node.\n\n**Options:**\n- `connectionUri: string` - Node connection string (pubkey or pubkey@host:port)\n- `usdCents: number` - Amount in cents (minimum 500 = $5.00)\n- `redirectUrl?: string` - Optional post-payment redirect URL\n- `privateChannel?: boolean` - Create private channel (default: false)\n- `railsClusterOnly?: boolean` - Source only from Rails cluster (default: false)\n\n**Returns:** Lightning invoice string to complete the payment\n\n**Throws:** `MagmaClientError` on API or network errors\n\n### Examples\n\n**Basic purchase:**\n```typescript\nimport { MagmaClient } from '@ambosstech/magma-mcp';\n\nconst client = new MagmaClient();\n\nconst invoice = await client.buyLiquidity({\n  connectionUri: '024ae5a5f0b01850983009489ca89c85...',\n  usdCents: 500  // $5.00 minimum\n});\n\nconsole.log('Invoice:', invoice);\n```\n\n**With all options:**\n```typescript\nconst invoice = await client.buyLiquidity({\n  connectionUri: '024ae5a5f0b01850983009489ca89c85...@12.34.56.78:9735',\n  usdCents: 5000,  // $50.00\n  redirectUrl: 'https://myapp.com/payment-complete',\n  privateChannel: true,\n  railsClusterOnly: true\n});\n```\n\n**Error handling:**\n```typescript\nimport { MagmaClient, ErrorCategory } from '@ambosstech/magma-mcp';\n\nconst client = new MagmaClient();\n\ntry {\n  const invoice = await client.buyLiquidity({\n    connectionUri: '024ae5a5f0b01850983009489ca89c85...',\n    usdCents: 1000\n  });\n  console.log('Success:', invoice);\n} catch (error) {\n  if (error.category === ErrorCategory.NETWORK_ERROR) {\n    console.error('Network issue, please retry');\n  } else if (error.category === ErrorCategory.CLIENT_ERROR) {\n    console.error('Invalid request:', error.message);\n  } else {\n    console.error('Unexpected error:', error);\n  }\n}\n```\n\n**TypeScript types:**\n```typescript\nimport type {\n  MagmaClientConfig,\n  BuyLiquidityOptions,\n  LiquidityOrderInput,\n  BuyLiquidityResponse\n} from '@ambosstech/magma-mcp';\n```\n\n### Advanced Usage\n\nFor advanced use cases, you can access the low-level GraphQL client:\n\n```typescript\nimport { MagmaGraphQLClient } from '@ambosstech/magma-mcp';\n\nconst client = new MagmaGraphQLClient({\n  magmaApiKey: 'your-api-key',\n  magmaEndpoint: 'https://magma.amboss.tech/graphql',\n  logLevel: 'debug'\n});\n\nconst response = await client.buyLiquidity({\n  connection_uri: '024ae5a5f0b01850983009489ca89c85...',\n  usd_cents: '1000',\n  options: {\n    private: true\n  }\n});\n\n// Full response structure\nconsole.log(response.liquidity.buy.payment.lightning_invoice);\n```\n\n## Development\n\n### Run in development mode\n\n```bash\npnpm dev\n```\n\n### Build\n\n```bash\npnpm build\n```\n\n### Type checking\n\n```bash\npnpm typecheck\n```\n\n### Test with MCP Inspector\n\nThe [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a great tool for testing your server:\n\n```bash\npnpm inspector\n```\n\nThis will open a web interface where you can:\n- View available tools\n- Test tool execution\n- Inspect requests and responses\n- Debug errors\n\n## Testing\n\n### Manual Testing with Claude Desktop\n\n1. Configure Claude Desktop with the MCP server\n2. Restart Claude Desktop\n3. Ask Claude to buy Lightning liquidity\n4. Verify the response includes a Lightning invoice\n\n### Example Test Conversation\n\n```\nYou: Can you buy $5 of Lightning liquidity for my node?\nClaude: I'll help you buy Lightning liquidity. I need your node's connection URI in the format pubkey@host:port.\nYou: 024ae5a5f0b01850983009489ca89c85...@12.34.56.78:9735\nClaude: [Executes buy_lightning_liquidity tool]\nClaude: Successfully created liquidity order! Transaction ID: abc123...\n      Here's your Lightning invoice: lnbc...\n      Payment URL: https://checkout.btcpay.amboss.tech/...\n```\n\n## Troubleshooting\n\n### Server won't start\n\n**Check environment variables:**\n```bash\nnode -e \"require('dotenv').config(); console.log(process.env.MAGMA_API_KEY)\"\n```\n\n**Check build output:**\n```bash\nls -la dist/\n```\n\n### Authentication errors\n\n**Error:** `Authentication failed. Please check your MAGMA_API_KEY.`\n\n**Solution:**\n1. If using an API key, verify it at https://account.amboss.tech/settings/api-keys\n2. Ensure the key is correctly set in your `.env` file or Claude config\n3. Check for extra spaces or quotes around the API key\n4. Alternatively, remove the API key to use anonymous access (the API will create a temporary account automatically)\n\n### Connection URI validation errors\n\n**Error:** `Connection URI must be either a 66-character pubkey or pubkey@host:port format`\n\n**Solution:**\n- Ensure pubkey is exactly 66 hexadecimal characters\n- Accepted formats:\n  - Just pubkey: `024ae5a5f0b01850983009489ca89c85...` (no spaces)\n  - With socket: `pubkey@host:port` (e.g., `024ae5...@12.34.56.78:9735`)\n- If using socket format, port must be between 1-65535\n\n### Minimum purchase amount error\n\n**Error:** `Minimum purchase amount is $5.00 (500 cents)`\n\n**Solution:** Use at least 500 cents ($5.00) for the `usd_cents` parameter.\n\n## Project Structure\n\n```\nmagma-mcp/\n├── src/\n│   ├── index.ts                 # Main MCP server entry point\n│   ├── config.ts                # Configuration with validation\n│   ├── lib/\n│   │   ├── graphql-client.ts    # Magma API client\n│   │   ├── tools/\n│   │   │   └── buy-liquidity.ts # Buy liquidity tool handler\n│   │   └── schemas/\n│   │       ├── common-schemas.ts        # Shared validation schemas\n│   │       └── buy-liquidity-schema.ts  # Buy tool schema\n│   └── types/\n│       └── magma.ts             # TypeScript types\n├── dist/                        # Compiled JavaScript (generated)\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n## Security\n\n- **API keys are never logged** - All logging goes to stderr and keys are sanitized\n- **Environment-based configuration** - API keys stored in `.env` or MCP config\n- **Input validation** - All inputs are validated before processing\n- **Error sanitization** - Errors never expose sensitive information\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Links\n\n- [Amboss Technologies](https://amboss.tech/)\n- [Magma Documentation](https://docs.amboss.tech/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [Get API Key](https://account.amboss.tech/settings/api-keys)\n\n## Support\n\n- **Issues:** [GitHub Issues](https://github.com/AmbossTech/magma-mcp/issues)\n- **Amboss Discord:** [Join Discord](https://discord.gg/amboss)\n- **Documentation:** [Amboss Docs](https://docs.amboss.tech/)\n\n---\n\nMade with ⚡ by [Amboss Technologies](https://amboss.tech/)\n","readmeFilename":"README.md"}