{"id":51129735,"url":"https://github.com/lnbits/lnbits-agent-wallet-mcp","last_synced_at":"2026-06-25T11:01:17.426Z","repository":{"id":364044966,"uuid":"1246707036","full_name":"lnbits/lnbits-agent-wallet-mcp","owner":"lnbits","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-11T11:09:17.000Z","size":49,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T13:09:50.156Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/lnbits.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":null,"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-05-22T13:20:08.000Z","updated_at":"2026-06-11T11:09:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lnbits/lnbits-agent-wallet-mcp","commit_stats":null,"previous_names":["lnbits/lnbits-agent-wallet-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/lnbits/lnbits-agent-wallet-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnbits%2Flnbits-agent-wallet-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnbits%2Flnbits-agent-wallet-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnbits%2Flnbits-agent-wallet-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnbits%2Flnbits-agent-wallet-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lnbits","download_url":"https://codeload.github.com/lnbits/lnbits-agent-wallet-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnbits%2Flnbits-agent-wallet-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34771664,"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-25T02:00:05.521Z","response_time":101,"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-25T11:01:14.522Z","updated_at":"2026-06-25T11:01:17.380Z","avatar_url":"https://github.com/lnbits.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LNbits Agent Wallet MCP\n\nA small stdio MCP server for the LNbits `agent_wallet` extension runtime API.\n\nThis project is intentionally narrow. It is **not** a generic LNbits wallet MCP and it does **not** use LNbits invoice/admin wallet keys. It only calls the LNbits `agent_wallet` extension's profile-scoped runtime endpoints. The `agent_wallet` extension remains the security boundary: profile lookup, ACL bearer-token authentication, policy enforcement, wallet selection, payment execution, and audit logging all happen inside LNbits.\n\n## What It Exposes\n\nThe MCP surface is intentionally small:\n\n- `get_status` — read profile status, policy, budget/capabilities summary\n- `create_invoice` — request a receive invoice\n- `dry_run_payment` — validate a payment/LNURL action without executing it\n- `pay_invoice` — request payment of a BOLT11 invoice\n- `pay_lightning_address` — request payment to a Lightning address\n- `claim_lnurl_withdraw` — claim an LNURL-withdraw into the bound receive wallet\n- `list_activity` — read recent agent activity/audit events\n\n`claim_lnurl_withdraw` accepts an optional `amount_sats`. If omitted, the `agent_wallet` runtime resolves the LNURL-withdraw request and uses `maxWithdrawable`.\n\n## Requirements\n\nYou need:\n\n1. An LNbits instance with the `agent_wallet` extension installed and configured.\n2. An `agent_wallet` profile ID for the agent you want this MCP server to use.\n3. A restricted `agent_wallet` ACL bearer token for that profile.\n4. [`uv`](https://docs.astral.sh/uv/) installed on the machine running your MCP client.\n\n## Configuration\n\nRequired environment variables:\n\n- `LNBITS_URL` — LNbits base URL, for example `https://lnbits.example.com`\n- `LNBITS_AGENT_TOKEN` — restricted `agent_wallet` ACL bearer token\n- `LNBITS_AGENT_PROFILE_ID` — `agent_wallet` profile ID to scope runtime requests\n\nOptional environment variables:\n\n- `LNBITS_AGENT_TIMEOUT` — request timeout in seconds, default `30`\n- `LNBITS_AGENT_RUNTIME_BASE_PATH` — defaults to `/agent_wallet/api/v1`\n\nAuthentication is always sent as:\n\n```http\nAuthorization: Bearer \u003cLNBITS_AGENT_TOKEN\u003e\n```\n\n## Install From Git With uvx\n\nUse `uvx` to run the package directly from git. This keeps the project uvx-ready without requiring a manual clone or package install.\n\n```bash\nLNBITS_URL=https://your-lnbits.example \\\nLNBITS_AGENT_TOKEN=restricted-runtime-token \\\nLNBITS_AGENT_PROFILE_ID=agent-wallet-profile-id \\\nuvx --from git+https://github.com/talvasconcelos/lnbits-agent-wallet-mcp.git \\\n  lnbits-agent-wallet-mcp\n```\n\nFor a pinned revision, use:\n\n```bash\nuvx --from git+https://github.com/talvasconcelos/lnbits-agent-wallet-mcp.git@\u003ccommit-sha\u003e \\\n  lnbits-agent-wallet-mcp\n```\n\nThis is a stdio MCP server. When launched directly it waits for an MCP client on stdin/stdout; it is normal for it not to print a CLI help screen.\n\n## Quick Setup\n\n1. Open the LNbits `agent_wallet` extension.\n2. Create or select the agent profile you want this MCP server to use.\n3. Copy the profile ID and restricted ACL bearer token from the extension's MCP/connector output.\n4. Open your MCP client's configuration file or MCP connector UI.\n5. Add a server named `lnbits_agent_wallet` using the command, arguments, and environment variables below.\n6. Restart or reload your MCP client.\n7. Ask the client to list MCP tools. You should see tools such as `get_status`, `create_invoice`, and `pay_invoice`.\n\n## MCP Connector Configuration\n\nMost MCP clients need the same connector shape: a command, arguments, and environment variables.\n\nUse this JSON shape for clients such as Claude Desktop, Codex, OpenCode/OpenClaw, and other MCP-compatible hosts when they accept JSON server configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"lnbits_agent_wallet\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/talvasconcelos/lnbits-agent-wallet-mcp.git\",\n        \"lnbits-agent-wallet-mcp\"\n      ],\n      \"env\": {\n        \"LNBITS_URL\": \"https://your-lnbits.example\",\n        \"LNBITS_AGENT_TOKEN\": \"restricted-runtime-token\",\n        \"LNBITS_AGENT_PROFILE_ID\": \"agent-wallet-profile-id\"\n      }\n    }\n  }\n}\n```\n\nReplace the three placeholder values with the values from your LNbits `agent_wallet` extension.\n\n### Claude Desktop / JSON-Based Clients\n\nPaste the JSON block above into the client's MCP server configuration. For Claude Desktop, this usually means adding it under `mcpServers` in the Claude desktop config file, then restarting Claude.\n\n### Codex / OpenCode / OpenClaw\n\nUse the same server definition if your client supports MCP JSON configuration. If the client has a UI instead of a file, enter:\n\n- Server name: `lnbits_agent_wallet`\n- Command: `uvx`\n- Arguments: `--from`, `git+https://github.com/talvasconcelos/lnbits-agent-wallet-mcp.git`, `lnbits-agent-wallet-mcp`\n- Environment variables: `LNBITS_URL`, `LNBITS_AGENT_TOKEN`, `LNBITS_AGENT_PROFILE_ID`\n\n### Hermes Example\n\nHermes uses YAML configuration:\n\n```yaml\nmcp_servers:\n  lnbits_agent_wallet:\n    command: uvx\n    args:\n      - --from\n      - git+https://github.com/talvasconcelos/lnbits-agent-wallet-mcp.git\n      - lnbits-agent-wallet-mcp\n    env:\n      LNBITS_URL: https://your-lnbits.example\n      LNBITS_AGENT_TOKEN: restricted-runtime-token\n      LNBITS_AGENT_PROFILE_ID: agent-wallet-profile-id\n```\n\n### Local Development Checkout\n\nUse this only while developing from a local clone:\n\n```yaml\nmcp_servers:\n  lnbits_agent_wallet:\n    command: uv\n    args:\n      - --directory\n      - /path/to/lnbits-agent-wallet-mcp\n      - run\n      - lnbits-agent-wallet-mcp\n    env:\n      LNBITS_URL: https://your-lnbits.example\n      LNBITS_AGENT_TOKEN: restricted-runtime-token\n      LNBITS_AGENT_PROFILE_ID: agent-wallet-profile-id\n```\n\n## Expected LNbits Endpoints\n\nDefault paths are profile-scoped and intentionally narrow:\n\n- `GET /agent_wallet/api/v1/profiles/{profile_id}/runtime/status`\n- `POST /agent_wallet/api/v1/profiles/{profile_id}/runtime/invoice`\n- `POST /agent_wallet/api/v1/profiles/{profile_id}/runtime/dry-run`\n- `POST /agent_wallet/api/v1/profiles/{profile_id}/runtime/pay`\n- `GET /agent_wallet/api/v1/profiles/{profile_id}/activity`\n\nThe wrapper never calls `/api/v1/payments` directly.\n\n## Development Checks\n\n```bash\nuv run ruff check .\nuv run pytest -q\nuv build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flnbits%2Flnbits-agent-wallet-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flnbits%2Flnbits-agent-wallet-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flnbits%2Flnbits-agent-wallet-mcp/lists"}