Kura (蔵 — 守护宝物的地方)

面向 AI 代理的本地 EVM 钱包。 在 Mac 上，当 Claude 等 AI 进行互联网支付（x402）时，由人类用密码批准的钱包。

• 不是给人用的钱包（如 MetaMask）——而是面向 AI 代理

• 不是云端 SaaS——只在本地运行。密钥不会离开这台电脑。

• AI 请求支付 → 人用密码批准 → 执行

• 链是 Base（以太坊 L2，手续费几乎为零）。默认是测试网（Base Sepolia）

一览

[ AI 앱 (Claude Code / 데스크톱) ]
        │  MCP로 "결제해줘" 요청
        ▼
[ Kura 데스크톱 앱 ]  ← 승인 팝업 → 사람이 비밀번호 입력
        │  서명 (키는 이 앱 안에서만)
        ▼
[ Base 체인 / x402 페이실리테이터 ]  ← 실제 결제

密码只在 Kura 应用的输入框中输入。不会进入聊天窗口、MCP 或配置文件中的任何地方。

Related MCP server: cardzero-mcp

安装

Apple Silicon Mac（macOS 11 及以上）

(A) Homebrew

brew install --cask dinggi5/tap/kura

(B) 直接下载 DMG

从 Releases 下载 Kura_<版本>_aarch64.dmg 并打开，将 Kura 拖入 Applications 文件夹。

这是一个托管密钥的应用，所以如何确认收到的应用确实是我制作的，在 SECURITY.md 中连命令都写好了。

(C) 从源码构建

前置准备：Rust、Node.js（20.19+ 或 22.12+ — 需要 Vite 7）、macOS。

git clone https://github.com/dinggi5/kura.git
cd kura
git checkout v0.1.1   # 배포본과 같은 소스. 빼면 개발 중인 최신 코드가 받아져요
npm ci                # package-lock.json 그대로 설치 (install 은 버전이 올라갈 수 있어요)

# 개발 모드로 바로 실행
npm run tauri dev

# 앱으로 빌드해 /Applications에 설치
npm run tauri build -- --bundles app --no-sign
ditto src-tauri/target/release/bundle/macos/Kura.app /Applications/Kura.app
open /Applications/Kura.app

更新

应用会自动更新。
在设置 → 关于中查看版本和变更内容，然后点击立即安装并重新启动。

• 只有检查是自动的，安装始终需要手动点击。

• 收到的文件只有在验证签名正确后才会被安装（签名验证无法关闭）。详情写在 SECURITY.md 的"更新"一节中。

• 如果不想自动检查更新，可以在设置 → 关于 → 启动时检查中关闭。

卸载

⚠️ 即使删除应用，钱包也不会被删除。 密钥、设置、交易记录都在应用外部的 ~/.jigap 文件夹中，只删除应用的话它们会保留——这是为了避免意外丢失资产而故意这样设计的（brew uninstall --zap 也不会删除）。

# 앱만 제거 (지갑은 남음 — 나중에 다시 설치하면 그대로 이어서 써요)
brew uninstall --cask dinggi5/tap/kura   # 또는 /Applications/Kura.app 을 휴지통으로

如果想彻底删除这台 Mac 上的钱包，请务必按顺序操作：

1. 先确认 12 个单词的恢复短语在手边。 可以在应用顶部的钥匙按钮中重新查看。

2. 如果还有余额，请转到其他钱包。

3. 完全退出 Kura（右键点击菜单栏图标 → 退出）。如果还在运行，它会每隔几秒向 ~/.jigap 写入状态文件，所以删除的文件夹会立刻重新出现。

4. 也要退出连接了 Kura MCP 的 AI 工具（如 Claude Code）。

5. 如果开启了自动启动，请关闭它，或执行 rm ~/Library/LaunchAgents/Kura.plist（将应用拖入废纸篓删除时，这个文件会保留。用 brew uninstall --cask 删除时会一起删除）。

6. 然后执行 rm -rf ~/.jigap

如果没有 12 个单词就执行最后的 rm -rf ~/.jigap，那个钱包的资产任何人都无法找回。

首次运行

Kura 生活在菜单栏中。 运行后，屏幕顶部的菜单栏会出现一个仓库图标（◻︎），窗口只有在点击该图标时才会向下展开。点击其他位置就会关闭，应用会留在后台继续等待 AI 支付请求。要完全关闭，请右键点击图标 → 退出。（首次运行还没有钱包时，窗口会自动打开。）

1. 创建钱包 — 设置每次转账时都要输入的密码（8 位以上）。密钥会用这个密码加密存储（~/.jigap/wallet.enc）。

2. 备份助记词 — 会出现 12 个单词。这是资产真正的所有权证明，请写在纸上或密码管理器中。即使忘记密码，只要有 12 个单词就能找回：退出应用，先确认 12 个单词在手边，然后删除 ~/.jigap/wallet.enc 并重新运行应用，就可以通过首屏的导入恢复（也可以放入其他标准 BIP-39 钱包）。但如果没有 12 个单词就删除这个文件，资产将永远丢失。

3. 欢迎向导 — 会介绍充值、AI 连接、安全措施。随时可以通过顶部的 ⓘ 帮助 重新查看。

充值（USDC）

要支付，钱包里需要有 USDC（数字美元）。

• 在应用中点击接收，会显示地址和二维码。

• 从交易所或其他钱包发送时，必须选择 Base 网络。发送到其他网络会丢失资金。

• 测试网（默认） 不是真钱。点击接收界面的 Faucet 按钮领取免费测试币来练习。

• ETH 是可选的 — x402 支付的手续费由支付服务商代付，所以 ETH 为 0 也可以。只有在用应用的发送功能直接转账时，才需要少量用于支付 gas 的 ETH（Base 手续费约 1 美分）。充值只需 USDC 就足够了。

连接 AI（Claude）

在 AI 应用的 MCP 设置中注册 Kura 服务器即可连接。连接后，主屏幕会显示 "Claude 已连接" 徽章。从 0.1.2 开始，应用内置了 MCP 服务器，无需克隆源码或安装 Rust 即可连接。

最简单的方法 — 应用内的"AI 连接"屏幕

点击主屏幕上方的 "AI 未连接"徽章，会打开连接屏幕。

• Claude 桌面版 — 点击"连接"按钮，会弹出 Claude 的扩展安装窗口。只需点击"安装"即可。

• Claude Code — 一键注册（应用会代替你执行 claude mcp add）。从下次运行 claude 开始，在任何文件夹中都可以连接。

以下是手动完成同样操作的方法。

Claude 桌面版 — 一个扩展文件即可

从发布页面下载 kura-<version>.mcpb 并双击，Claude 桌面版会询问是否安装。（或者 Claude 设置 → 扩展 → 选择文件。）

扩展内没有可执行文件——只包含一个启动器，它会在验证签名后运行已安装的 Kura.app 内经过签名和公证的 MCP 服务器。所以需要先安装 Kura 应用。

Claude Code · 其他 MCP 应用

将应用内的二进制文件以绝对路径注册即可：

claude mcp add --scope user kura -- /Applications/Kura.app/Contents/MacOS/kura-mcp

（--scope user 是"不仅限于这个文件夹"，而是让它在任何地方都能使用的选项。如果只想在一个项目中使用，可以省略。）

其他 MCP 应用在设置中这样填写：

{
  "mcpServers": {
    "kura": {
      "command": "/Applications/Kura.app/Contents/MacOS/kura-mcp"
    }
  }
}

如果在源码中开发

仓库根目录的 .mcp.json 已经存在。在这个文件夹中运行 claude 时会自动被识别（第一次会询问是否使用服务器，批准即可）。这个路径是每次用 cargo run 重新构建的开发用路径——如果要安装使用，请注册上面的应用路径。

AI 可以使用的工具：get_wallet_status · get_balances · get_history（只读）· request_payment（支付请求 → 应用批准弹窗）· x402_fetch（调用遇到 402 支付的 URL）。

更改 MCP 工具后，需要重启 AI 应用才能生效（服务器在会话开始时加载一次）。

支付流程如下

1. AI 请求支付。

2. Kura 窗口弹出，显示金额和去向（即使窗口隐藏也会自动弹出）。

3. 输入密码并批准。

4. 支付执行，结果返回给 AI。5 分钟内未批准则自动拒绝。

安全模型

• 密码批准 — 默认每次支付都需要密码批准（开启自主支付时，仅在以下条件下例外）。密钥加密（Argon2id + AES-256-GCM）存储，仅在支付时解密并立即清除（开启自主支付会话时，仅在解锁期间保存在内存中）。

• 限额 — 在设置中设定单次/每日可发送的金额上限（默认单次 5 · 每日 20 USDC）。超过则被阻止。

• 紧急锁定 — 开启顶部的盾牌按钮，所有转账立即被阻止。

• 信任地址 · 自主支付 — 要在无需密码的情况下自动批准，必须同时满足会话解锁 + 小额限额 + 信任地址三个条件。否则始终需要密码。

• 交易记录 — 记录所有已发送的转账、被阻止的尝试和签名。

• 本地优先 — 密钥（~/.jigap/）在仓库之外，不会上传到 git。

• 无分析、无字体 CDN — 应用自行连接互联网的情况只有三种：①用于余额查询和转账的 RPC 服务器 ②AI 请求的 x402 地址 ③更新检查（GitHub）。使用记录不会发送到任何地方，字体也内置在应用中，因此离线时屏幕也能正常显示。

• 更新检查可以关闭 — 启动应用时会向 GitHub 询问是否有新版本（那边会留下访问 IP 和当前版本）。在设置 → 关于 → 启动时检查中关闭，这个通信也会消失。无论检查开启还是关闭，安装都需要手动点击——不会悄悄更改。

开发者

也可以使用 CLI kura 操作同一个钱包（与 MCP 服务器共享核心逻辑）。它已经包含在已安装的应用中，只需在 PATH 中添加一行即可使用：

sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/Kura.app/Contents/MacOS/kura-cli /usr/local/bin/kura
kura status

从源码运行时：

cargo run --manifest-path ./kura-mcp/Cargo.toml --bin kura -- status
cargo run --manifest-path ./kura-mcp/Cargo.toml --bin kura -- balance
cargo run --manifest-path ./kura-mcp/Cargo.toml --bin kura -- history --limit 10
cargo run --manifest-path ./kura-mcp/Cargo.toml --bin kura -- pay <주소> <금액> --token usdc
cargo run --manifest-path ./kura-mcp/Cargo.toml --bin kura -- fetch <URL>

pay/fetch 不接受 CLI 密码 — 需要 Kura 应用正在运行，并且人在批准弹窗中输入密码。

测试：

(cd src-tauri && cargo test)        # 백엔드(지갑·암호화·한도·송금)
(cd kura-mcp && cargo test)         # MCP/CLI 어댑터
npx tsc --noEmit && npx vite build  # 프론트

制作发行版（签名、公证的 DMG）的流程在 docs/RELEASE.md 中。需要 Apple Developer 账户和一次性设置，之后只需一行：

./scripts/release.sh

技术栈

结构：[Rust 核心(src-tauri)] ← MCP / CLI 适配器(kura-mcp)。密钥访问（签名）仅由 GUI 进程执行——这是最终防线。

许可证 · 状态

MIT 许可证 — 这是处理密钥和资金的代码，我认为应该可以直接阅读、验证和修改。

如果发现漏洞，请在提交 issue 之前通过 SECURITY.md 中的非公开渠道告知。同一文档中也记录了 Kura 无法阻止的事情。

随附的 Pretendard 字体采用 SIL Open Font License 1.1（全文）。

第一优先用户是本人——这是为在 Apple Silicon Mac 上使用本地 LLM/Claude 进行支付的韩国开发者、创作者设计的钱包。目前还是 0.1.x 早期版本，建议先在默认的测试网上熟悉，在主网上只放入可以承受损失的金额。