Bitcoin MCP Server

Instructions

Implementation Reference

• src/server/tools.ts:163-188 (handler)

  Handler function that validates input using GetTransactionSchema, fetches transaction via bitcoinService, and formats the response as MCP TextContent.

  export async function handleGetTransaction(
    bitcoinService: BitcoinService,
    args: unknown
  ) {
    const result = GetTransactionSchema.safeParse(args);
    if (!result.success) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Invalid parameters: ${result.error.message}`
      );
    }
  
    const tx = await bitcoinService.getTransaction(result.data.txid);
    return {
      content: [
        {
          type: "text",
          text: `Transaction details:\nTXID: ${tx.txid}\nStatus: ${
            tx.status.confirmed ? "Confirmed" : "Unconfirmed"
          }\nBlock Height: ${tx.status.blockHeight || "Pending"}\nFee: ${
            tx.fee
          } sats`,
        },
      ] as TextContent[],
    };
  }

• src/types.ts:126-128 (schema)

  Zod schema defining the input for get_transaction: txid as 64-char string.

  export const GetTransactionSchema = z.object({
    txid: z.string().length(64, "Invalid transaction ID"),
  });

• src/server/base.ts:152-161 (registration)

  Tool registration in listTools handler: defines name, description, and inputSchema for 'get_transaction'.

    name: "get_transaction",
    description: "Get transaction details",
    inputSchema: {
      type: "object",
      properties: {
        txid: { type: "string", description: "Transaction ID" },
      },
      required: ["txid"],
    },
  } as Tool,

• src/server/base.ts:212-214 (registration)

  Dispatch in CallToolRequestSchema handler: routes 'get_transaction' calls to handleGetTransaction.

  case "get_transaction": {
    return handleGetTransaction(this.bitcoinService, args);
  }

• src/services/bitcoin.ts:212-257 (helper)

  BitcoinService method that fetches transaction details from Blockstream API and maps to TransactionInfo type.

  async getTransaction(txid: string): Promise<TransactionInfo> {
    try {
      const response = await fetch(`${this.apiBase}/tx/${txid}`);
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      const tx = (await response.json()) as any;
      return {
        txid: tx.txid,
        version: tx.version,
        locktime: tx.locktime,
        size: tx.size,
        weight: tx.weight,
        fee: tx.fee,
        status: {
          confirmed: tx.status.confirmed,
          blockHeight: tx.status.block_height,
          blockHash: tx.status.block_hash,
          blockTime: tx.status.block_time,
        },
        inputs: tx.vin.map((input: any) => ({
          txid: input.txid,
          vout: input.vout,
          sequence: input.sequence,
          prevout: input.prevout
            ? {
                value: input.prevout.value,
                scriptPubKey: input.prevout.scriptpubkey,
                address: input.prevout.scriptpubkey_address,
              }
            : undefined,
        })),
        outputs: tx.vout.map((output: any) => ({
          value: output.value,
          scriptPubKey: output.scriptpubkey,
          address: output.scriptpubkey_address,
        })),
      };
    } catch (error) {
      logger.error({ error, txid }, "Failed to get transaction");
      throw new BitcoinError(
        "Failed to get transaction",
        BitcoinErrorCode.BLOCKCHAIN_ERROR
      );
    }
  }