Bitcoin SV MCP Server

Una colección de herramientas para interactuar con la blockchain de Bitcoin SV (BSV), incluyendo funciones de billetera, ordinales y utilidades.

GitHub
22
Prueba este MCPPatrocinado

Documentación

BSV MCP

BSV MCP conecta tu asistente de IA con Bitcoin SV. Pídele que verifique una transacción, muestre tu saldo, envíe un pago, o cree e intercambie ordinales (contenido registrado en la blockchain).

Documentación · Todas las herramientas · npm · Problemas

Instalación

Instala Bun para ejecutar el servidor y Node.js para los comandos npx a continuación, luego agrégalo a tu cliente:

# Codex
codex mcp add bsv-mcp -- npx -y bsv-mcp@latest --stdio

# Claude Code
claude mcp add --transport stdio bsv-mcp -- npx -y bsv-mcp@latest --stdio

# Grok Build
grok plugin install b-open-io/bsv-mcp --trust

Elige un comando. Para Cursor o Claude Desktop, usa esta configuración de servidor:

{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "bsv-mcp@latest", "--stdio"]
    }
  }
}

Reinicia tu cliente y luego pregunta: "Ejecuta bsv_status y explica qué está disponible." El stdio local no necesita cuenta Sigma ni inicio de sesión OAuth. También es el predeterminado cuando no se especifica transporte. El HTTP autoalojado existente sigue siendo opcional mediante TRANSPORT=http; el endpoint alojado implementado no cambia.

Para el plugin de escritorio de Codex, agrega b-open-io/claude-plugins en el marketplace de plugins e instala BSV MCP. El plugin inicia el ejecutable npm local y requiere Node.js y Bun. Los plugins de Claude Code y Grok incluyen el servidor local y requieren Bun. Elige un registro para evitar herramientas duplicadas.

Conecta una billetera

Pide a tu asistente que ejecute wallet_onboarding. Crea, importa o desbloquea una Vault en el navegador local. Haz una copia de seguridad antes de financiarla. Ingresa contraseñas solo en la interfaz de configuración local, nunca en el chat. Después de reiniciar el servidor, desbloquéala nuevamente.

Para usar una billetera BRC-100 existente, configura su API de firma en su lugar:

{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "bsv-mcp@latest", "--stdio"],
      "env": {
        "BRC100_WALLET_URL": "http://127.0.0.1:3321",
        "BRC100_WALLET_ORIGINATOR": "bsv-mcp.local"
      }
    }
  }
}

La billetera conserva sus claves y controla las solicitudes de permisos. Su API de firma es separada de un endpoint de almacenamiento de billetera. Consulta configuración de billetera para ajustes de red, selección de cuenta y roles de proyecto.

El paquete también incluye el lanzador bsv-mcp-local basado en Bun para configuraciones externas explícitas, integradas heredadas y de proyecto. Los ejemplos de checkout de código fuente están en la guía de instalación.

Compatibilidad con el protocolo MCP

La revisión de protocolo 2026-07-28 es la preferida, con clientes 2025 compatibles aceptados automáticamente en stdio y HTTP. No se necesita anulación de compatibilidad. Configura MCP_LEGACY_COMPATIBILITY=false solo para exigir clientes modernos. Esta configuración también se transmite a través del lanzador local. El cliente de escritorio instalado fue verificado usando solicitudes heredadas; el soporte moderno se prueba por separado.

Los clientes modernos admiten operaciones de billetera y aprobación con alcance de solicitud. Las continuaciones de aprobación conservan la operación original y se vinculan a su usuario autenticado, argumentos y caducidad. Rechazar, cancelar o revocar la sesión detiene la operación; reproducir una continuación no repite una transacción. Un cliente sin obtención de formularios no puede aprobar un gasto. Las billeteras externas conservan su propio flujo de permisos del firmante. La ruta alojada expone solo lecturas públicas.

Para el cliente SDK v2 dividido:

const client = new Client(
  { name: "my-app", version: "1" },
  { versionNegotiation: { mode: "auto" }, capabilities: { elicitation: { form: {} } } },
);

Registra un manejador de aprobación humano real antes de usar herramientas que dependen de aprobación. La compatibilidad con protocolo heredado está habilitada por defecto; el cliente conectado debe admitir el flujo de aprobación requerido por la herramienta solicitada.

El catálogo completo de herramientas sigue siendo el predeterminado y se deriva de capacidades: el modo de billetera, los módulos habilitados, el contexto de cuenta y el perfil seleccionado determinan qué tools/list devuelve. El manifiesto verificado es una línea base sintética para un servidor configurado, no una promesa de un recuento predeterminado fijo. Configura MCP_TOOL_CATALOG=compact solo para optar por familias de lectura limitadas; el modo compacto usa los mismos manejadores subyacentes. La disponibilidad de herramientas aún depende del modo de billetera y los módulos habilitados. Sus familias de lectura de línea base son bsv_read, ordinals_read, wallet_read y utility, cada una con una enumeración de operaciones limitada; las operaciones desconocidas se rechazan. Las sesiones elegibles también exponen familias de mutación separadas wallet_setup y wallet_payments. Consulta la guía de soporte de protocolo de cliente MCP para los límites de operaciones por familia, contratos de endpoint, compatibilidad con MCP Apps y estado de validación.

Social

Dos herramientas cubren operaciones sociales en catálogos completos y compactos:

  • bsocial_read: publicaciones, respuestas, búsqueda, me gusta, amigos, canales, mensajes, videos e historial de acciones sin procesar.
  • bsocial_publish: publicaciones/respuestas, republicaciones, me gusta/no me gusta, seguir/dejar de seguir, registros de amigo/no amigo, mensajes y registros de video. Las etiquetas y adjuntos usan salidas firmadas por separado e independientemente.
{"action":{"type":"post","content":"Hello Bitcoin","tags":["bitcoin"]},"preview":true}

La vista previa devuelve salidas sin firmar sin usar claves ni gastar. Elimina preview para publicar a través de los permisos existentes de la billetera de identidad seleccionada. Los mensajes son públicos a menos que su contenido se haya cifrado previamente; un contexto de destinatario no los cifra. Los registros de amigos publicitan una clave pública de comunicación de un flujo de acuerdo de claves establecido.

Consulta la guía social para ejemplos y migración desde los nombres de herramientas antiguos. PUBLIC_BMAP_URL es la raíz del servidor indexador (con rutas /social y /q), no una billetera ni una API de identidad. Los registros sin procesar de seguir/dejar de seguir son historial de eventos, no una afirmación sobre el estado actual de la relación.

Modos de billetera local

El modo externo se conecta a un firmante BRC-100 existente. El firmante conserva las claves privadas, el almacenamiento de la billetera y las decisiones de permisos; BSV MCP recibe solo la interfaz del firmante SDK. El modo integrado usa una billetera Vault local cifrada. La pantalla lista para billetera muestra una nube interactiva de las herramientas disponibles de la sesión conectada, generada desde su catálogo en vivo.

Cuando se necesita configuración, wallet_onboarding abre el flujo de navegador privado para crearla, importarla o desbloquearla. La base de datos de la cuenta seleccionada y la configuración de almacenamiento permanecen en uso. El modo integrado de cuenta existente del lanzador aún proporciona BSV_MCP_PASSWORD en tiempo de ejecución. El modo de proyecto abre cada rol asignado explícitamente: payments, identity-signing, one-sat y encryption. Requiere selectores de proyecto emparejados y BSV_MCP_PASSWORD en tiempo de ejecución; configura VAULT_PATH cuando el módulo Vault no proporcione una ruta predeterminada. Los enlaces fijan la clave pública seleccionada y admiten claves directas, hijos BRC-42 y hojas de perfil BRC-157/Yours. Cambiar el enlace del proyecto o expirar su sesión revoca los manejadores capturados. Las claves derivadas tienen almacenamiento separado; seleccionar la raíz de pago de la cuenta conserva su base de datos existente y el prefijo de depósito.

Las herramientas BRC-100 aceptan walletRole (payments, identity, ordinals o encryption). Los valores predeterminados del método seleccionan el rol coincidente, y las continuaciones de acción de firma/anulación conservan su billetera de origen y usuario autenticado. Un rol no asignado falla en lugar de tomar prestada otra clave. Las herramientas BAP usan la billetera de identidad para publicación, rotación, atestaciones y perfiles sin exportar un xprv. Esa billetera también financia esas transacciones y conserva los registros BAP. Las publicaciones BSocial firmadas y las inscripciones SIGMA usan la identidad configurada.

Los registros externos pueden usar el mismo par raíz/ID de proyecto para derivar un origen de permisos aislado, sin contraseña de Vault. El opcional BRC100_WALLET_PUBLIC_KEY fija la identidad del firmante. BRC100_WALLET_ROLES es un objeto JSON que selecciona endpoints de roles independientes y fijaciones de clave pública; consulta configuración de firmante externo. El lanzador de código fuente acepta external --project-root /absolute/project --project-id project.example. Su valor predeterminado es transmisión deshabilitada; configura DISABLE_BROADCASTING=false en su entorno de ejecución para habilitar herramientas de transacción con la aprobación del firmante.

Cada modo tiene su propio entorno de proceso y debe registrarse como un servidor separado cuando necesites cambiar entre ellos. Usa solo los registros necesarios para el proyecto.

Las billeteras integradas pueden listar pagos PeerPay pendientes y recibir un pago seleccionado con wallet_peerPayments. Recibir requiere un ID de mensaje y reconoce el mensaje solo después de que la billetera lo acepte. Estas operaciones no pagan tarifas de servicio de MessageBox. Los firmantes externos y Droplit no exponen esta herramienta. Las sesiones de proyecto requieren un rol de pago asignado.

Encuentra una habilidad

Usa utils_find_skills con una consulta de palabra clave corta para encontrar habilidades en el catálogo bOpen. Devuelve hasta cinco descripciones y enlaces a archivos SKILL.md versionados. No descarga contenidos de habilidades ni instala plugins. En modo compacto, selecciona utils_find_skills de la herramienta utility.

Los avisos de tutorial estáticos y el catálogo de recursos BRC/BitCom se han retirado. Usa el buscador de habilidades para esas referencias. El registro de cambios, la documentación de JungleBus y el recurso de la aplicación de panel permanecen disponibles.

Trae tu billetera e infraestructura

Conecta una billetera existente compatible con BRC100_WALLET_URL, o usa la configuración del navegador Vault local (wallet_onboarding). BSV_MCP_PASSWORD es solo para agentes sin cabeza: configúralo en el entorno de proceso para esa sesión, nunca en la configuración del cliente MCP. PRIVATE_KEY_WIF y IDENTITY_KEY_WIF son fuentes de migración, no claves de firma en vivo; impórtalas a Vault y elimina las copias en texto plano. El inicio nunca crea claves. Consulta la guía de configuración de billetera para la API de billetera requerida y la configuración.

El backend de API 1Sat predeterminado es https://api.1sat.app. Las cuentas integradas nuevas de mainnet usan https://wallet.1sat.app para el almacenamiento de billetera por defecto; las cuentas de testnet no seleccionan un proveedor de almacenamiento remoto a menos que se configuren. Anula ONESAT_API_URL para servicios de API y REMOTE_STORAGE_URL para almacenamiento de billetera; estos son ajustes separados. Las herramientas disponibles dependen del modo de billetera y los módulos habilitados.

Desarrollo

bun install
bun run dev          # Website
bun run build:all    # MCP server and dashboard
# Supply BRC100_WALLET_URL in the host environment before this launch.
bun --no-env-file scripts/local-mcp-launcher.ts external # Source-checkout local launch
bun test

Software experimental; las API pueden cambiar. Mantén una copia de seguridad de la billetera. Si una solicitud de transacción agota el tiempo de espera, verifica si tuvo éxito antes de enviarla nuevamente. Licencia MIT.

Preparación de un paquete de lanzamiento

package.json "files" es el tarball. prepack ejecuta bun run build:all. Publica con bun publish. Las bibliotecas de tiempo de compilación son devDependencies; los consumidores obtienen los archivos dist/ incluidos, no una segunda copia del árbol de código fuente.