{"_rev":"12-f30f1abccce0f38bb14e04aaee91b5e5","time":{"created":"2026-07-07T05:11:35.046Z","modified":"2026-07-07T05:11:35.653Z","0.0.1":"2026-07-07T04:00:44.844Z","0.0.2":"2026-07-07T04:14:38.573Z","0.0.3":"2026-07-07T04:21:43.921Z","0.0.4":"2026-07-07T04:24:03.102Z","0.0.5":"2026-07-07T04:31:10.637Z","0.0.6":"2026-07-07T04:42:13.724Z","0.0.7":"2026-07-07T04:53:11.363Z","0.0.8":"2026-07-07T05:11:35.380Z"},"_id":"@bitdancelabs/bitpocket-local-mcp","name":"@bitdancelabs/bitpocket-local-mcp","dist-tags":{"latest":"0.0.8"},"versions":{"0.0.8":{"name":"@bitdancelabs/bitpocket-local-mcp","version":"0.0.8","description":"`@bitdancelabs/bitpocket-local-mcp` is a local wallet MCP Server built on the [Model Context Protocol](https://modelcontextprotocol.io/). The process runs on the user's own machine and communicates with MCP clients (Claude Desktop / Claude Code / Cursor, ","main":"dist/index.js","bin":{"bitpocket-local-mcp":"dist/index.js"},"scripts":{"build":"esbuild src/index.ts --bundle --platform=node --format=cjs --banner:js=\"#!/usr/bin/env node\" --outfile=dist/index.js --external:tiny-secp256k1 --external:secp256k1","dev":"tsx watch src/index.ts","test":"tsx --test tests/*.test.ts","prepublishOnly":"npm run build"},"keywords":["bitpocket local mcp","bitdance wallet mcp","bitdance local mcp","bitpocket","naka mcp","bitpocket mcp"],"author":{"name":"bitdance-labs"},"license":"MIT","type":"commonjs","repository":{"type":"git","url":"git+https://github.com/bitdancelabs/bitpocket-local-mcp.git"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","bip32":"^4.0.0","bip39":"^3.1.0","bitcoinjs-lib":"^6.1.5","bitcoinjs-message":"^2.2.0","buffer":"^6.0.3","ecpair":"^2.1.0","tiny-secp256k1":"^2.2.3"},"devDependencies":{"@dcloudio/types":"^3.4.8","@dcloudio/uni-automator":"3.0.0-4050720250324001","@dcloudio/uni-cli-shared":"3.0.0-4050720250324001","@dcloudio/uni-stacktracey":"3.0.0-4050720250324001","@dcloudio/vite-plugin-uni":"3.0.0-4050720250324001","@types/node":"^20.0.0","@vue/runtime-core":"^3.4.21","autoprefixer":"^10.4.23","crypto-browserify":"^3.12.1","crypto-js":"^4.2.0","dotenv":"^17.4.2","ed25519-hd-key":"^1.3.0","esbuild":"^0.28.1","ethers":"^6.11.1","moment":"^2.30.1","pinia":"^2.0.36","postcss":"^8.5.6","qrcode.vue":"^3.6.0","randomstring":"^1.2.3","sass":"^1.87.0","stream":"^0.0.3","stream-browserify":"^3.0.0","tronweb":"^6.2.2","tsx":"^4.0.0","typescript":"^5.0.0","vite":"5.2.8","vite-plugin-javascript-obfuscator":"^3.1.0","vite-plugin-node-polyfills":"^0.23.0","vite-plugin-wasm":"^3.4.1","vue":"^3.5.11","vue-i18n":"^9.1.9"},"gitHead":"195f13e990a4e2e849b90f649bd0eb8cdbaa7ffe","_id":"@bitdancelabs/bitpocket-local-mcp@0.0.8","bugs":{"url":"https://github.com/bitdancelabs/bitpocket-local-mcp/issues"},"homepage":"https://github.com/bitdancelabs/bitpocket-local-mcp#readme","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-ZqPeS0RCa+cgSm1VorhxIqipgErn3IrR1nGcUqwYPWDYXRfBS26qcfnJmZgZfIta/dbN4Jdv7sDoXeMm8XvL/A==","shasum":"2fcbf5b9ee65166a61cdf5282ef7ae36d233704b","tarball":"https://registry.npmjs.org/@bitdancelabs/bitpocket-local-mcp/-/bitpocket-local-mcp-0.0.8.tgz","fileCount":3,"unpackedSize":1475008,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEBqv0KRJi1GdQBc5m7cKO2GGXXzpXRBaTFJJDidaeGBAiEAmPtxn20jO6O/0I4k3CrIhXke26umdKZTQgnchHiCtu8="}]},"_npmUser":{"name":"bitdancelabs-dev","email":"bitdance2025@gmail.com"},"directories":{},"maintainers":[{"name":"bitdancelabs-dev","email":"bitdance2025@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/bitpocket-local-mcp_0.0.8_1783401095245_0.8610025225540472"},"_hasShrinkwrap":false}},"maintainers":[{"name":"bitdancelabs-dev","email":"bitdance2025@gmail.com"}],"description":"`@bitdancelabs/bitpocket-local-mcp` is a local wallet MCP Server built on the [Model Context Protocol](https://modelcontextprotocol.io/). The process runs on the user's own machine and communicates with MCP clients (Claude Desktop / Claude Code / Cursor, ","homepage":"https://github.com/bitdancelabs/bitpocket-local-mcp#readme","keywords":["bitpocket local mcp","bitdance wallet mcp","bitdance local mcp","bitpocket","naka mcp","bitpocket mcp"],"repository":{"type":"git","url":"git+https://github.com/bitdancelabs/bitpocket-local-mcp.git"},"author":{"name":"bitdance-labs"},"bugs":{"url":"https://github.com/bitdancelabs/bitpocket-local-mcp/issues"},"license":"MIT","readme":"# bitpocket-local-mcp\n\n<p align=\"center\">\n  <em>A local wallet MCP tool for the BitPocket ecosystem, provided by <strong>BitDanceLabs</strong></em>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/bitdancelabs/bitpocket-local-mcp\">https://github.com/bitdancelabs/bitpocket-local-mcp</a>\n</p>\n\n---\n\n---\n\n## Configuring in MCP Clients(For Users)\n\n### Claude Code\nAppend the following mcp tool to `~/.claude.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"bitpocket-local-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bitdancelabs/bitpocket-local-mcp@latest\"],\n      \"env\": {\n        \"BTC_MNEMONIC\": \"<your mnemonic>\"\n      }\n    }\n  }\n}\n```\n\n\n### OpenCode\nAppend the following mcp tool to `~/.config/opencode/opencode.json`\n\n```json\n{\n  \"mcp\": {\n    \"bitpocket-local-mcp\":{\n      \"type\": \"local\",\n      \"command\": [\n        \"npx\",\n        \"-y\",\n        \"@bitdancelabs/bitpocket-local-mcp@latest\"\n      ],\n      \"environment\": {\n        \"BTC_MNEMONIC\": \"<your mnemonic>\"\n      }\n    }\n  }\n}\n```\n\n## Background\n\n**BitDanceLabs** is positioned as the infrastructure provider for the other organizations, benchmarked against Lightning Labs. It is responsible for the underlying protocols, wallets, and signing toolchains, so that upper-layer applications such as BitBoom and BitPocket can focus on their business.\n\nWithin the BitPocket MCP toolchain we provide two MCP Servers that work together:\n\n| MCP Server | Where it runs | Role | Does the private key ever leave the user's machine? |\n| --- | --- | --- | --- |\n| **bitpocket-local-mcp** (this repo) | User's local machine | Hosts the wallet and performs signing on the user's machine; provides \"key-never-leaves\" offline signing | ✅ Private key always stays on the user's machine |\n\nTypical collaboration flow between the two:\n\n```\n  AI Agent (Claude / Cursor / ...)\n        │\n        ├── Other MCPs ──►  Other MCPs that needs to communicate with bitopcket local mcp, such as naka-api-mcp/bitpocket-api-mcp/bitboom-api-mcp...\n        │\n        └── bitpocket-local-mcp  ──►  Local wallet (signing, address derivation)\n```\n\n> bitpocket-api-mcp hands the \"to-be-signed\" PSBT to the AI; the AI then passes the PSBT to the local bitpocket-local-mcp to sign; the signed result is passed back by the AI to bitpocket-api-mcp for broadcasting. The private key never enters the server and never enters the LLM context.\n\n---\n\n## What is bitpocket-local-mcp?\n\n`bitpocket-local-mcp` is a local wallet MCP Server built on the [Model Context Protocol](https://modelcontextprotocol.io/). The process runs on the user's own machine and communicates with MCP clients (Claude Desktop / Claude Code / Cursor, etc.) over stdio.\n\nIts core positioning:\n\n- **Local**: The process runs on the user's machine; the mnemonic and private key are loaded and used only in local memory.\n- **Signing only**: It does not initiate on-chain transactions, does not broadcast, and does not go online — it only does two things: \"derive address\" and \"sign\".\n- **Service-oriented**: It standardizes \"who performs the signing\", so AI agents and upper-layer applications can invoke wallet capabilities like any ordinary tool without caring about the underlying key implementation details.\n- **Pairs with bitpocket-api-mcp**: Acts as the \"secure signing backend\" for bitpocket-api-mcp, forming a standard \"online + offline\" combination.\n\n---\n\n## Provided Tools\n\nThis MCP Server exposes 4 tools:\n\n| Tool name | Purpose | Notes |\n| --- | --- | --- |\n| `bitpocket_wallet_get_address` | Derive the BitPocket local wallet's Taproot address from `BTC_MNEMONIC` according to the configured `NETWORK`, and persist the public wallet information to a local JSON file | Read-only / idempotent |\n| `bitpocket_wallet_sign_btc_psbt` | Sign a BTC PSBT with the local wallet | Supports `auto_finalized` and optional input selection |\n| `bitpocket_wallet_sign_ta_psbt` | Sign a Taproot Assets PSBT with the local wallet, returning the `tapKeySig` for each signed input | For Taproot Assets scenarios only |\n| `bitpocket_wallet_sign_message` | Generate a BTC ECDSA message signature for an arbitrary string with the local wallet | Used for authentication / message verification |\n\n### 1. `bitpocket_wallet_get_address`\n\nDerives and returns the wallet's public information (address, public key, fingerprint, derivation paths, etc.), and caches the result in a local JSON file to avoid repeated derivation.\n\n- **Input**: none.\n- **Output**: wallet address, public key, x-only public key, fingerprint, account/asset public keys and their derivation paths, network, local storage path, etc.\n\n### 2. `bitpocket_wallet_sign_btc_psbt`\n\nSigns a BTC PSBT.\n\n**Input parameters:**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `psbt` | string (base64) | ✅ | The PSBT to be signed |\n| `auto_finalized` | boolean | ❌ | Whether to attempt finalize after signing, default `false` |\n| `to_sign_inputs` | array | ❌ | Specifies which inputs to sign; omitting or an empty array means sign all signable inputs |\n\nStructure of each `to_sign_inputs` element:\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `index` | number | ✅ | The input index to sign (non-negative integer) |\n| `public_key` | string | ❌ | Public key identifier passed by the caller; kept for compatibility only, not used for local key selection |\n| `address` | string | ❌ | Address identifier passed by the caller; kept for compatibility only, not used for local key selection |\n| `sighash_types` | number[] | ❌ | Allowed sighash type list |\n| `disable_tweak_signer` | boolean | ❌ | Whether to disable the Taproot tweak signer |\n| `use_tweaked_signer` | boolean | ❌ | Whether to use the Taproot tweaked signer; takes precedence over `disable_tweak_signer` |\n\n### 3. `bitpocket_wallet_sign_ta_psbt`\n\nSigns a Taproot Assets PSBT and returns the `tapKeySig` for each signed input.\n\n- The input schema is identical to `bitpocket_wallet_sign_btc_psbt` (`psbt` / `auto_finalized` / `to_sign_inputs`).\n- Difference: targets the Taproot Assets asset-layer signing; signing always uses the tweaked signer, the related parameters are retained for compatibility, and finalize is not performed locally.\n\n### 4. `bitpocket_wallet_sign_message`\n\nGenerates a BTC ECDSA message signature (base64) for an arbitrary string.\n\n**Input parameters:**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | string | ✅ | The string to be signed (non-empty) |\n\n**Output:** `network`, `walletAddress`, `message`, `signature` (base64), etc.\n\n---\n\n## Environment Variables\n\nAll wallet configuration is provided via environment variables:\n\n| Variable | Description | Values |\n| --- | --- | --- |\n| `BTC_MNEMONIC` | Wallet mnemonic (BIP39) | Required. **Used only in local memory; never written to any file / log / network** |\n\n> ⚠️ **Security note**: The mnemonic is the sovereignty over the assets. Make sure `BTC_MNEMONIC` is injected only via a local environment variable — never commit it to a repository, never write it in plaintext into a Claude config file, and never print it to logs.\n\n\n---------------------\n## Install and Build(For Developers)\n```bash\n# Install dependencies\nnpm install\n\n# Compile TypeScript\nnpm run build\n\n# Local development (watch mode)\nnpm run dev\n```\n\nBuild output goes to the `dist/` directory.\n\n---\n\n## Working with bitpocket-api-mcp (Recommended Usage)\n\nA complete \"on-chain interaction + local signing\" flow is typically organized like this:\n\n1. The AI calls a `naka-api-mcp`,`bitboom-api-mcp` or any other mcp tool to have the server construct a transaction and returns a base64 **PSBT**.\n2. The AI passes the PSBT to the local `bitpocket_wallet_sign_btc_psbt` (BTC) / `bitpocket_wallet_sign_ta_psbt` (Taproot Assets) for signing.\n3. The AI passes the signed PSBT back to `bitpocket-api-mcp`, which finalizes and broadcasts it.\n\nThis guarantees:\n\n- The server never touches the private key;\n- The mnemonic or private key never appears in the AI / LLM context;\n- Any environment outside the user's machine can only ever see the \"signed PSBT\", which is safe to transmit.\n\n---\n\n## License\n\nMIT © BitDance-Labs\n","readmeFilename":"README.md"}