{"id":50496765,"url":"https://github.com/lightninglabs/lightning-agent-tools","last_synced_at":"2026-06-02T08:03:07.133Z","repository":{"id":361143757,"uuid":"1151717511","full_name":"lightninglabs/lightning-agent-tools","owner":"lightninglabs","description":"AI agent toolkit (skills+MCP server) for Lightning Network payments. Run nodes, pay for APIs (L402), host paid endpoints, and manage credentials. ","archived":false,"fork":false,"pushed_at":"2026-05-29T09:59:23.000Z","size":324,"stargazers_count":46,"open_issues_count":11,"forks_count":14,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-29T11:24:04.195Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lightninglabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T20:12:36.000Z","updated_at":"2026-05-29T09:59:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lightninglabs/lightning-agent-tools","commit_stats":null,"previous_names":["lightninglabs/lightning-agent-tools"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/lightninglabs/lightning-agent-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightninglabs%2Flightning-agent-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightninglabs%2Flightning-agent-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightninglabs%2Flightning-agent-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightninglabs%2Flightning-agent-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lightninglabs","download_url":"https://codeload.github.com/lightninglabs/lightning-agent-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightninglabs%2Flightning-agent-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33812204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T08:03:06.328Z","updated_at":"2026-06-02T08:03:07.124Z","avatar_url":"https://github.com/lightninglabs.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lightning Agent Tools\n\nAI agents can read documentation, write code, and orchestrate complex workflows,\nbut they can't easily pay for things. Traditional payment rails require\ngovernment IDs, bank accounts, and manual enrollment, none of which work for\nautonomous software. Lightning Agent Tools bridges this gap by giving agents\nnative access to the [Lightning Network](https://lightning.network), a\ndecentralized payment protocol capable of instant, high-volume transactions with\nno identity requirements.\n\nThe toolkit consists of seven composable skills and an MCP server. Together they\nlet an agent run a Lightning node, pay for resources on the web using the\n[L402](https://docs.lightning.engineering/the-lightning-network/l402) protocol,\nhost its own paid API endpoints, manage scoped credentials, and query node state\nthrough the Model Context Protocol. The skills work with any agent framework\nthat can execute shell commands: [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview),\n[Codex](https://openai.com/index/codex/), or your own tooling. The MCP server\nfollows the [Model Context Protocol](https://modelcontextprotocol.io) standard\nand works with any compatible client. The security model defaults to a remote\nsigner architecture that keeps private keys on a separate machine, away from the\nagent's runtime environment.\n\n## Install\n\n**MCP server** (zero-install, any MCP client):\n\n```bash\nclaude mcp add --transport stdio lnc -- npx -y @lightninglabs/lightning-mcp-server\n```\n\n**Full plugin** (all 7 skills via Claude Code):\n\n```bash\nclaude plugin marketplace add lightninglabs/lightning-agent-tools\nclaude plugin install lightning-agent-tools@lightninglabs\n```\n\n**From source** (requires Go 1.24+):\n\n```bash\ngit clone https://github.com/lightninglabs/lightning-agent-tools.git\ncd lightning-agent-tools\nskills/lightning-mcp-server/scripts/install.sh\nskills/lightning-mcp-server/scripts/configure.sh --production\nskills/lightning-mcp-server/scripts/setup-claude-config.sh --scope project\n```\n\nSee [Quick Start](#quick-start) below for detailed setup options including\nenvironment variables, regtest mode, and the full commerce stack.\n\n## How It Works\n\n```mermaid\ngraph TD\n    CC[\"Your Agent\"] --\u003e Skills\n\n    subgraph Skills[\"Skills\"]\n        lnd[\"lnd\u003cbr/\u003e\u003ci\u003erun a Lightning node\u003c/i\u003e\"]\n        lsm[\"lightning-security-module\u003cbr/\u003e\u003ci\u003eremote signer\u003c/i\u003e\"]\n        mb[\"macaroon-bakery\u003cbr/\u003e\u003ci\u003escoped credentials\u003c/i\u003e\"]\n        lg[\"lnget\u003cbr/\u003e\u003ci\u003eL402 HTTP client\u003c/i\u003e\"]\n        ap[\"aperture\u003cbr/\u003e\u003ci\u003eL402 reverse proxy\u003c/i\u003e\"]\n        mcp[\"lightning-mcp-server\u003cbr/\u003e\u003ci\u003eMCP server\u003c/i\u003e\"]\n        com[\"commerce\u003cbr/\u003e\u003ci\u003ebuyer/seller workflows\u003c/i\u003e\"]\n    end\n\n    subgraph Runtime[\"Daemons \u0026 Tools\"]\n        lnd_d[\"lnd daemon\"]\n        signer_d[\"lnd signer\"]\n        aperture_d[\"aperture proxy\"]\n        lnget_d[\"lnget CLI\"]\n        mcp_d[\"lightning-mcp-server\"]\n    end\n\n    lnd --\u003e lnd_d\n    lsm --\u003e signer_d\n    lg --\u003e lnget_d\n    ap --\u003e aperture_d\n    mcp --\u003e mcp_d\n\n    lnd_d \u003c--\u003e|\"remote signing\"| signer_d\n    lnget_d --\u003e|\"pays invoices\"| lnd_d\n    aperture_d --\u003e|\"generates invoices\"| lnd_d\n    mcp_d \u003c--\u003e|\"LNC tunnel\"| lnd_d\n\n    com -.-\u003e lnd\n    com -.-\u003e lg\n    com -.-\u003e ap\n```\n\nThe skills break down into three functional groups:\n\n**Payment infrastructure.** The `lnd` skill runs a Lightning node using the\nNeutrino light client (no full Bitcoin node required) with SQLite storage. The\n`lightning-security-module` sets up a remote signer to hold private keys on a\nseparate machine. The `macaroon-bakery` bakes least-privilege credentials so\nagents only get the permissions they need.\n\n**Commerce.** The `lnget` skill installs a command-line HTTP client that handles\nL402 payments automatically. When it hits a 402 response, it pays the embedded\nLightning invoice, caches the token, and retries. The `aperture` skill runs an\nL402 reverse proxy that gates access to a backend service behind Lightning\ninvoices. The `commerce` skill ties these together into buyer and seller\nworkflows.\n\n**Node access.** The `lightning-mcp-server` skill builds and configures an MCP server that\nconnects to a Lightning node via Lightning Node Connect (encrypted WebSocket\ntunnels, pairing-phrase auth, no stored credentials). It exposes 18 read-only\ntools for querying node state and works with any MCP-compatible client.\n\n## Quick Start\n\n### Option A: Zero-Install MCP via `claude mcp add`\n\nRegister the MCP server with Claude Code in one command — no Go toolchain or\ngit clone required:\n\n```bash\nclaude mcp add --transport stdio lnc -- npx -y @lightninglabs/lightning-mcp-server\n```\n\nWith a specific mailbox server:\n\n```bash\nclaude mcp add --transport stdio \\\n  --env LNC_MAILBOX_SERVER=mailbox.terminal.lightning.today:443 \\\n  lnc -- npx -y @lightninglabs/lightning-mcp-server\n```\n\nFor development/regtest:\n\n```bash\nclaude mcp add --transport stdio \\\n  --env LNC_MAILBOX_SERVER=localhost:11110 \\\n  --env LNC_DEV_MODE=true \\\n  --env LNC_INSECURE=true \\\n  lnc -- npx -y @lightninglabs/lightning-mcp-server\n```\n\nScope options: `--scope local` (default, just you), `--scope project` (shared\nvia `.mcp.json`), `--scope user` (all your projects).\n\nRestart Claude Code, then:\n\n```\nConnect to my Lightning node with pairing phrase: \"word1 word2 ... word10\"\n```\n\nThe agent can now query balances, list channels, decode invoices, and inspect\nthe network graph. See [MCP Server](docs/mcp-server.md) for details.\n\n### Option B: Full Plugin with All Skills\n\nInstall the complete plugin (all 7 skills + MCP server) via the Claude Code\nplugin marketplace:\n\n```bash\n# Add the marketplace (one-time)\nclaude plugin marketplace add lightninglabs/lightning-agent-tools\n\n# Install the plugin (gets all skills)\nclaude plugin install lightning-agent-tools@lightninglabs\n```\n\nOr load locally for development:\n\n```bash\ngit clone https://github.com/lightninglabs/lightning-agent-tools.git\nclaude --plugin-dir ./lightning-agent-tools\n```\n\nThis gives Claude Code access to all skills: lnd node management, remote\nsigner security, lnget L402 payments, Aperture proxy, macaroon bakery,\nMCP server integration, and commerce workflows.\n\n### Option C: Read-Only Node Access (from source)\n\nBuild the MCP server from source. Requires Go 1.24+.\n\n```bash\ngit clone https://github.com/lightninglabs/lightning-agent-tools.git\ncd lightning-agent-tools\n\nskills/lightning-mcp-server/scripts/install.sh\nskills/lightning-mcp-server/scripts/configure.sh --production\nskills/lightning-mcp-server/scripts/setup-claude-config.sh --scope project\n```\n\nRestart Claude Code, then:\n\n```\nConnect to my Lightning node with pairing phrase: \"word1 word2 ... word10\"\n```\n\nThe agent can now query balances, list channels, decode invoices, and inspect\nthe network graph. See [MCP Server](docs/mcp-server.md) for details.\n\n### Option D: Full Commerce Stack\n\nRun your own node and start buying or selling resources over Lightning. Docker\nis the default deployment method — `install.sh` pulls a container image and\n`start-lnd.sh` launches it via Docker Compose.\n\n```bash\ngit clone https://github.com/lightninglabs/lightning-agent-tools.git\ncd lightning-agent-tools\n\n# Install components (pulls Docker images by default; --source to build natively)\nskills/lnd/scripts/install.sh\nskills/lnget/scripts/install.sh\n\n# Create and start a node (runs in a Docker container)\nskills/lnd/scripts/create-wallet.sh --mode standalone\nskills/lnd/scripts/start-lnd.sh\n\n# Configure lnget\nlnget config init\n\n# Fetch a paid resource\nlnget --max-cost 500 https://api.example.com/data.json\n```\n\nAll wrapper scripts (`start-lnd.sh`, `stop-lnd.sh`, `lncli.sh`) auto-detect\nDocker containers. Pass `--native` to any script to use a locally built binary\ninstead.\n\nFor the full walkthrough including wallet funding, channel management, and\nhosting your own paid endpoints, see [Commerce](docs/commerce.md).\n\n### Natural Language\n\nAgents with skill discovery (like Claude Code) pick up the skills automatically.\nYou can interact through natural language:\n\n```\nInstall Lightning Agent Tools and set up a Lightning node with\nremote signer so I can start paying for L402 APIs with lnget.\n```\n\n```\nBake a pay-only macaroon on my regtest node\n```\n\n```\nExport credentials from my signer and set up a watch-only node\n```\n\n## Skills\n\n| Skill | What it does |\n|-------|-------------|\n| **lnd** | Installs and operates an lnd Lightning node. Neutrino light client, SQLite storage. Defaults to watch-only mode with remote signer. |\n| **lightning-security-module** | Sets up a remote signer node on a separate machine. Holds all private keys; the agent machine has none. |\n| **macaroon-bakery** | Bakes scoped macaroons (pay-only, invoice-only, read-only, channel-admin, signer-only) for least-privilege access. |\n| **lnget** | Command-line HTTP client with automatic L402 payment. Pays Lightning invoices on 402 responses, caches tokens, retries. |\n| **aperture** | L402 reverse proxy. Sits in front of a backend service, issues invoices, validates paid tokens, proxies authorized requests. |\n| **lightning-mcp-server** | Builds and configures the MCP server for LNC-based read-only access to a Lightning node. 18 tools, no stored credentials. |\n| **commerce** | Meta-skill orchestrating lnd + lnget + aperture for end-to-end buyer/seller workflows. |\n\nAll scripts support `--container` for Docker-based lnd nodes and `--rpcserver`\n/ `--tlscertpath` / `--macaroonpath` for remote nodes.\n\n## Security\n\nThe kit provides three tiers of access with increasing trust requirements:\n\n```mermaid\ngraph LR\n    subgraph T1[\"Tier 1: Watch-Only + Remote Signer\"]\n        A1[\"Agent: no keys\"]\n        S1[\"Signer: holds keys\"]\n        A1 ---|\"gRPC\"| S1\n    end\n\n    subgraph T2[\"Tier 2: Standalone\"]\n        A2[\"Agent: keys on disk (0600)\"]\n    end\n\n    subgraph T3[\"Tier 3: Read-Only via LNC\"]\n        A3[\"Agent: no credentials on disk\"]\n    end\n\n    T1 --- P1[\"Production\"]\n    T2 --- P2[\"Testing\"]\n    T3 --- P3[\"Observation\"]\n```\n\n**Tier 1 (default)** splits the node into a watch-only instance on the agent\nmachine and a signer on a separate machine. The agent can route payments and\nmanage channels but cannot sign transactions. Keys never leave the signer.\n\n**Tier 2** stores keys locally. Appropriate for testnet, regtest, and small-value\nmainnet experiments.\n\n**Tier 3** uses the MCP server with LNC. No credentials are written to disk;\nthe pairing phrase is handled in memory and ephemeral ECDSA keypairs are\ngenerated per session.\n\nFor all tiers, use the `macaroon-bakery` to scope credentials. A buyer agent\ngets a `pay-only` macaroon; a monitoring agent gets `read-only`. Never hand out\n`admin.macaroon` in production.\n\nSee [Security](docs/security.md) for threat models, hardening, and the\nproduction checklist.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Architecture](docs/architecture.md) | System design, component map, plugin discovery, data flows |\n| [Security](docs/security.md) | Three-tier security model, remote signer, macaroon scoping, production checklist |\n| [L402 and lnget](docs/l402-and-lnget.md) | The L402 protocol, lnget usage, spending controls, token caching |\n| [MCP Server](docs/mcp-server.md) | LNC mechanics, setup walkthrough, 18-tool reference, configuration |\n| [Commerce](docs/commerce.md) | Buyer and seller agent setup, the commerce loop, cost management |\n| [Two-Agent Setup](docs/two-agent-setup.md) | Signer agent + node agent walkthrough for production key isolation |\n| [Quick Reference](docs/quickref.md) | Every command in one place |\n\nEach skill also has a detailed `SKILL.md` in its directory under `skills/` with\noperational reference material: script options, configuration templates, file\npaths, and troubleshooting.\n\n## Prerequisites\n\n- **Docker** for running lnd/litd containers (the default deployment method)\n- **Go 1.21+** only needed when building from source (`install.sh --source`) or\n  for lnget and the MCP server\n- **jq** for JSON processing in shell scripts\n- **Lightning Terminal** (optional) for generating LNC pairing phrases\n\nContainer image versions are pinned in `versions.env` at the repository root and\ncan be overridden via environment variables.\n\n## License\n\nSee [LICENSE](lightning-mcp-server/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightninglabs%2Flightning-agent-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flightninglabs%2Flightning-agent-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightninglabs%2Flightning-agent-tools/lists"}