Magma

Node.js client library and Model Context Protocol (MCP) server for buying Lightning Network liquidity via Amboss Magma.

Overview

This package provides two ways to interact with the Amboss Magma API:

1. Node.js Client Library: Programmatically buy Lightning liquidity from your Node.js applications
2. MCP Server: Enable AI assistants like Claude to purchase inbound Lightning Network liquidity for your node

Both interfaces provide a seamless way to increase your node's receiving capacity through the Amboss Magma API.

Features

• Buy Lightning Liquidity: Purchase inbound liquidity for your Lightning node
• Anonymous Access: Works without an API key - the Magma API creates temporary accounts automatically
• Optional Authentication: Use your Amboss account API key for personalized access
• Input Validation: Comprehensive validation of all parameters
• Error Handling: Clear, user-friendly error messages
• Retry Logic: Automatic retry for transient network failures

Prerequisites

• Node.js >= 18.0.0
• pnpm (or npm/yarn)
• A Lightning Network node with accessible connection URI
• (Optional) Amboss Magma API key (Get one here)

Installation

From npm (Recommended)

npm install -g @ambosstech/magma-mcp

Or with pnpm:

pnpm add -g @ambosstech/magma-mcp

From source

git clone https://github.com/AmbossTech/magma-mcp.git
cd magma-mcp
pnpm install
pnpm build

Configure environment variables (Optional)

The Magma API supports anonymous access - you can use the server without an API key! The API will automatically create temporary accounts with session keys.

If you want to use your existing Amboss account, create a .env file:

cp .env.example .env

Edit .env and add your Magma API key:

MAGMA_API_KEY=your_api_key_here

Configuration

Environment Variables

Variable	Required	Default	Description
MAGMA_API_KEY	No	-	Your Amboss Magma API key (optional - supports anonymous access)
MAGMA_GRAPHQL_ENDPOINT	No	https://magma.amboss.tech/graphql	Magma GraphQL endpoint
LOG_LEVEL	No	info	Logging level (debug, info, warn, error)

Claude Desktop Integration

Add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Using npm package (anonymous access)

{
  "mcpServers": {
    "magma": {
      "command": "npx",
      "args": ["-y", "@ambosstech/magma-mcp"]
    }
  }
}

Option 2: Using npm package (with API key)

{
  "mcpServers": {
    "magma": {
      "command": "npx",
      "args": ["-y", "@ambosstech/magma-mcp"],
      "env": {
        "MAGMA_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option 3: From source (development)

{
  "mcpServers": {
    "magma": {
      "command": "node",
      "args": ["/absolute/path/to/magma-mcp/dist/server.js"],
      "env": {
        "MAGMA_API_KEY": "your_api_key_here"
      }
    }
  }
}

After adding the configuration:

1. Save the file
2. Restart Claude Desktop
3. The Magma MCP server will be available

Usage

Once configured, you can use natural language with Claude to buy Lightning liquidity:

Example Prompts

Basic purchase:

Buy $10 of Lightning liquidity for my node at [email protected]:9735

With options:

Buy $50 of Lightning liquidity for [email protected]:9735
using only Rails cluster nodes

Private channel:

Buy $25 of private channel liquidity for my node [email protected]:9735

Tool: buy_lightning_liquidity

Parameters:

• connection_uri (required): Your node's connection string (either just pubkey or pubkey@host:port)
  • Just pubkey: 024ae5a5f0b01850983009489ca89c85...
  • With socket: [email protected]:9735
• usd_cents (required): Dollar amount in cents (minimum 500 = $5.00)
• redirect_url (optional): URL to redirect after payment
• private_channel (optional): Create private channel (default: false)
• rails_cluster_only (optional): Source only from Rails cluster (default: false)

Returns:

{
  "success": true,
  "lightning_invoice": "lnbc10m1p3j8z9xpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypq..."
}

The Lightning invoice can be paid using any Lightning wallet to complete the liquidity purchase.

Using as a Node.js Library

In addition to the MCP server, this package can be used as a Node.js client library to programmatically interact with the Amboss Magma API.

Installation

npm install @ambosstech/magma-mcp

Quick Start

import { MagmaClient } from '@ambosstech/magma-mcp';

// Create client (anonymous access)
const client = new MagmaClient();

// Or with API key
const client = new MagmaClient({
  apiKey: process.env.MAGMA_API_KEY
});

// Buy liquidity
const invoice = await client.buyLiquidity({
  connectionUri: '[email protected]:9735',
  usdCents: 1000  // $10.00
});

console.log('Pay this Lightning invoice:', invoice);

API Reference

MagmaClient

Constructor:

new MagmaClient(config?: MagmaClientConfig)

Config options:

• apiKey?: string - Your Amboss Magma API key (optional, supports anonymous access)
• endpoint?: string - GraphQL endpoint (default: https://magma.amboss.tech/graphql)
• logLevel?: 'debug' | 'info' | 'error' - Logging level (default: error)

Methods:

buyLiquidity(options: BuyLiquidityOptions): Promise<string>

Purchase inbound Lightning Network liquidity for a node.

Options:

• connectionUri: string - Node connection string (pubkey or pubkey@host:port)
• usdCents: number - Amount in cents (minimum 500 = $5.00)
• redirectUrl?: string - Optional post-payment redirect URL
• privateChannel?: boolean - Create private channel (default: false)
• railsClusterOnly?: boolean - Source only from Rails cluster (default: false)

Returns: Lightning invoice string to complete the payment

Throws: MagmaClientError on API or network errors

Examples

Basic purchase:

import { MagmaClient } from '@ambosstech/magma-mcp';

const client = new MagmaClient();

const invoice = await client.buyLiquidity({
  connectionUri: '024ae5a5f0b01850983009489ca89c85...',
  usdCents: 500  // $5.00 minimum
});

console.log('Invoice:', invoice);

With all options:

const invoice = await client.buyLiquidity({
  connectionUri: '[email protected]:9735',
  usdCents: 5000,  // $50.00
  redirectUrl: 'https://myapp.com/payment-complete',
  privateChannel: true,
  railsClusterOnly: true
});

Error handling:

import { MagmaClient, ErrorCategory } from '@ambosstech/magma-mcp';

const client = new MagmaClient();

try {
  const invoice = await client.buyLiquidity({
    connectionUri: '024ae5a5f0b01850983009489ca89c85...',
    usdCents: 1000
  });
  console.log('Success:', invoice);
} catch (error) {
  if (error.category === ErrorCategory.NETWORK_ERROR) {
    console.error('Network issue, please retry');
  } else if (error.category === ErrorCategory.CLIENT_ERROR) {
    console.error('Invalid request:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

TypeScript types:

import type {
  MagmaClientConfig,
  BuyLiquidityOptions,
  LiquidityOrderInput,
  BuyLiquidityResponse
} from '@ambosstech/magma-mcp';

Advanced Usage

For advanced use cases, you can access the low-level GraphQL client:

import { MagmaGraphQLClient } from '@ambosstech/magma-mcp';

const client = new MagmaGraphQLClient({
  magmaApiKey: 'your-api-key',
  magmaEndpoint: 'https://magma.amboss.tech/graphql',
  logLevel: 'debug'
});

const response = await client.buyLiquidity({
  connection_uri: '024ae5a5f0b01850983009489ca89c85...',
  usd_cents: '1000',
  options: {
    private: true
  }
});

// Full response structure
console.log(response.liquidity.buy.payment.lightning_invoice);

Development

Run in development mode

pnpm dev

Build

pnpm build

Type checking

pnpm typecheck

Test with MCP Inspector

The MCP Inspector is a great tool for testing your server:

pnpm inspector

This will open a web interface where you can:

• View available tools
• Test tool execution
• Inspect requests and responses
• Debug errors

Testing

Manual Testing with Claude Desktop

1. Configure Claude Desktop with the MCP server
2. Restart Claude Desktop
3. Ask Claude to buy Lightning liquidity
4. Verify the response includes a Lightning invoice

Example Test Conversation

You: Can you buy $5 of Lightning liquidity for my node?
Claude: I'll help you buy Lightning liquidity. I need your node's connection URI in the format pubkey@host:port.
You: [email protected]:9735
Claude: [Executes buy_lightning_liquidity tool]
Claude: Successfully created liquidity order! Transaction ID: abc123...
      Here's your Lightning invoice: lnbc...
      Payment URL: https://checkout.btcpay.amboss.tech/...

Troubleshooting

Server won't start

Check environment variables:

node -e "require('dotenv').config(); console.log(process.env.MAGMA_API_KEY)"

Check build output:

ls -la dist/

Authentication errors

Error: Authentication failed. Please check your MAGMA_API_KEY.

Solution:

1. If using an API key, verify it at https://account.amboss.tech/settings/api-keys
2. Ensure the key is correctly set in your .env file or Claude config
3. Check for extra spaces or quotes around the API key
4. Alternatively, remove the API key to use anonymous access (the API will create a temporary account automatically)

Connection URI validation errors

Error: Connection URI must be either a 66-character pubkey or pubkey@host:port format

Solution:

• Ensure pubkey is exactly 66 hexadecimal characters
• Accepted formats:
  • Just pubkey: 024ae5a5f0b01850983009489ca89c85... (no spaces)
  • With socket: pubkey@host:port (e.g., [email protected]:9735)
• If using socket format, port must be between 1-65535

Minimum purchase amount error

Error: Minimum purchase amount is $5.00 (500 cents)

Solution: Use at least 500 cents ($5.00) for the usd_cents parameter.

Project Structure

magma-mcp/
├── src/
│   ├── index.ts                 # Main MCP server entry point
│   ├── config.ts                # Configuration with validation
│   ├── lib/
│   │   ├── graphql-client.ts    # Magma API client
│   │   ├── tools/
│   │   │   └── buy-liquidity.ts # Buy liquidity tool handler
│   │   └── schemas/
│   │       ├── common-schemas.ts        # Shared validation schemas
│   │       └── buy-liquidity-schema.ts  # Buy tool schema
│   └── types/
│       └── magma.ts             # TypeScript types
├── dist/                        # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Security

• API keys are never logged - All logging goes to stderr and keys are sanitized
• Environment-based configuration - API keys stored in .env or MCP config
• Input validation - All inputs are validated before processing
• Error sanitization - Errors never expose sensitive information

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Links

• Amboss Technologies
• Magma Documentation
• Model Context Protocol
• Get API Key

Support

• Issues: GitHub Issues
• Documentation: Amboss Docs

---

Made with ⚡ by Amboss Technologies