@fireblocks/mcp-server

Fireblocks MCP Server

A Model Context Protocol (MCP) server implementation for the Fireblocks API, enabling AI assistants to interact with Fireblocks services through a standardized protocol.

Overview

This MCP server provides secure access to Fireblocks functionality, allowing AI assistants to:

• Query and create transactions
• Retrieve and manage vault accounts and assets
• Access exchange account information
• Query network connections and policies
• Query blockchain information and whitelisted IP addresses
• Query external and internal wallets
• Query and filter workspace users

Prerequisites

Node.js (v18 or higher) - Download here

Installation

Step 1: Create an API key

To get started, you'll need a Fireblocks API Key and its corresponding secret key file.

• Follow the Fireblocks guide on creating an API key.

🔒 Security Note: When configuring an API user for the MCP server, it is critical to grant only the minimum permissions required for its specific tasks. For example, for read-only tasks like viewing transaction history, the "Viewer" role is the most secure option. For a detailed guide on user roles, please refer to the best practices for choosing user roles.

• Once created, securely store both the API Key and the secret key file (e.g., fireblocks-secret.key). You will need both for the next steps.

Step 2: Configure your MCP Client

For Claude Desktop

• Open Claude Desktop.
• Go to Settings → Developer → Edit Config to open the claude_desktop_config.json file.
• Add a new server with this configuration:

{
  "mcpServers": {
    "fireblocks": {
      "command": "npx",
      "args": ["@fireblocks/mcp-server"],
      "env": {
        "FIREBLOCKS_API_KEY": "your-api-key",
        "FIREBLOCKS_PRIVATE_KEY_PATH": "your-fireblocks-api-secret-key-filepath",
        "ENABLE_WRITE_OPERATIONS": "false",
        "FIREBLOCKS_API_BASE_URL": "https://api.fireblocks.io/v1"
      }
    }
  }
}

For Cursor

• Open Cursor.
• Go to Settings → Cursor Settings → Tools & Integrations.
• Select MCP Tools and click Add Custom MCP to open the mcp.json file.
• Add a new server with this configuration:

{
  "mcpServers": {
    "fireblocks": {
      "command": "npx",
      "args": ["@fireblocks/mcp-server"],
      "env": {
        "FIREBLOCKS_API_KEY": "your-api-key",
        "FIREBLOCKS_PRIVATE_KEY_PATH": "your-fireblocks-api-secret-key-filepath",
        "ENABLE_WRITE_OPERATIONS": "false",
        "FIREBLOCKS_API_BASE_URL": "https://api.fireblocks.io/v1"
      }
    }
  }
}

Step 3: Customize MCP Server Settings (Optional)

• To enable write operations, set the ENABLE_WRITE_OPERATIONS environment variable to true. Be sure to read the Security Considerations section before doing so.
• If you need to use a non-default Fireblocks environment (e.g., Non-US, Sandbox), set FIREBLOCKS_API_BASE_URL to the base URL of the specific environment's API.

Available Tools

The Fireblocks MCP server provides the following tools:

Transaction Management

get_transactions

Retrieve Fireblocks transactions with comprehensive filtering options.

Parameters:

• before (optional): Unix timestamp in milliseconds - get transactions before this date
• after (optional): Unix timestamp in milliseconds - get transactions after this date
• status (optional): Filter by transaction status
• orderBy (optional): Order by 'createdAt' or 'lastUpdated'
• sort (optional): Sort direction ('ASC' or 'DESC')
• limit (optional): Number of results (1-200, default: 50)
• sourceType (optional): Source type (VAULT_ACCOUNT, EXCHANGE_ACCOUNT, INTERNAL_WALLET, EXTERNAL_WALLET, CONTRACT, FIAT_ACCOUNT, NETWORK_CONNECTION, COMPOUND, UNKNOWN, GAS_STATION, END_USER_WALLET)
• sourceId (optional): Source ID
• destType (optional): Destination type (VAULT_ACCOUNT, EXCHANGE_ACCOUNT, INTERNAL_WALLET, EXTERNAL_WALLET, CONTRACT, FIAT_ACCOUNT, NETWORK_CONNECTION, COMPOUND, ONE_TIME_ADDRESS, END_USER_WALLET)
• destId (optional): Destination ID
• assets (optional): Comma-separated list of asset IDs
• txHash (optional): Filter by transaction hash
• sourceWalletId (optional): Filter by source wallet ID
• destWalletId (optional): Filter by destination wallet ID

create_transaction

Create a new transaction in Fireblocks.

Vault Management

get_vault_accounts

Retrieve vault accounts with filtering and pagination.

Parameters:

• namePrefix (optional): Filter by account name prefix
• nameSuffix (optional): Filter by account name suffix
• minAmountThreshold (optional): Filter accounts with balance above threshold
• assetId (optional): Filter by asset ID
• orderBy (optional): Sort direction ('ASC' or 'DESC')
• before (optional): Pagination cursor for previous results
• after (optional): Pagination cursor for next results
• limit (optional): Number of results (1-200, default: 50)

get_vault_account_by_id

Get details of a specific vault account by ID.

Parameters:

• vaultAccountId (required): The ID of the vault account to retrieve

get_vault_account_asset

Get asset information for a specific vault account.

Parameters:

• vaultAccountId (required): The ID of the vault account
• assetId (required): The ID of the asset

get_vault_assets

Get asset balance for chosen assets with optional filtering.

Parameters:

• accountNamePrefix (optional): Filter vault accounts by name prefix
• accountNameSuffix (optional): Filter vault accounts by name suffix

get_vault_balance_by_asset

Get vault balance information for a specific asset.

Parameters:

• assetId (required): The ID of the asset

Exchange Management

get_exchange_accounts

Retrieve exchange accounts with pagination.

Parameters:

• limit (optional): Number of results per page (1-5, default: 3)
• before (optional): Pagination cursor for previous results
• after (optional): Pagination cursor for next results

Network

get_network_connections

Retrieve network connection information.

Blockchain Information

get_blockchains

Retrieve information about supported blockchains.

get_blockchain_asset

Get asset information for a specific blockchain.

Parameters:

• id (required): The ID or legacyId of the blockchain asset

get_assets

Get assets supported by Fireblocks with comprehensive filtering options.

Parameters:

• blockchainId (optional): Blockchain ID of the assets
• assetClass (optional): Assets class (NATIVE, FT, FIAT, NFT, SFT)
• symbol (optional): Assets onchain symbol
• scope (optional): Scope of the assets (GLOBAL, LOCAL)
• deprecated (optional): Are assets deprecated (boolean)
• ids (optional): A list of asset IDs (max 100)
• pageCursor (optional): Next page cursor to fetch
• pageSize (optional): Items per page (100-1000, default: 500)

Wallet Management

get_external_wallets

Retrieve external wallets under the workspace.

get_internal_wallets

Retrieve internal wallets under the workspace.

Security & Governance

get_active_policy

Get the currently active policy configuration.

get_whitelist_ip_addresses

Retrieve whitelisted IP addresses.

User Management

get_users

List all users for the workspace with optional filtering (requires Admin permissions).

Parameters:

• id (optional): Filter users by specific user ID
• email (optional): Filter users by specific email address (case-insensitive)
• query (optional): Search users by name or email (case-insensitive partial matching)

Prompt Examples

Here are some example prompts you can use with the Fireblocks MCP server:

Show me all my vault accounts and their balances

Get the last 10 transactions from today

What is my total Bitcoin balance across all accounts?

Top up my Bitstamp account to have 1000 USDC or USDT

Why did the policy block my last transaction?

Note: Transaction creation and top-up examples require ENABLE_WRITE_OPERATIONS=true and appropriate permissions.

Security Considerations

The use of an AI assistant to interact with your Fireblocks workspace presents inherent risks. Since AI models may produce unintended results, it is imperative to implement a robust security strategy to safeguard your assets. The following practices are highly recommended:

Default Safe Configuration

⚠️ Security Warning: Write operations, such as creating transactions and modifying data in your Fireblocks workspace, are enabled by an AI assistant. For enhanced security, these operations (e.g., create_transaction) are disabled by default. They can be enabled by explicitly setting the ENABLE_WRITE_OPERATIONS environment variable to true. This should only be done in trusted environments with appropriate access controls.

Principle of Least Privilege

When configuring an API user for the MCP server, it is essential to grant only the minimum permissions necessary for its intended function. For read-only tasks, a "Viewer" role, which is restricted to viewing transaction history, is the most secure option.

For a detailed guide on user roles, please refer to the the best practices for choosing user roles.

Instructions for creating a new API user can be found in the Fireblocks guide on creating an API key.

Human in the Loop

We strongly advise utilizing the Fireblocks Policy Engine to ensure human oversight in the transaction approval process. A policy can be configured to require a manual designated signer to approve any transaction initiated by the AI assistant. More information can be found here.

Secure API Credentials

Your Fireblocks API Key and Private Key are highly sensitive credentials. Adherence to these best practices is mandatory:

• API credentials must never be shared publicly.
• The private key should be stored securely, preferably as a file with restricted access, as specified in the Configuration section.

How to develop in the repo

Getting Started

Follow these steps to set up the project for local development:

• Clone the repository

git clone https://github.com/fireblocks/fireblocks-mcp.git
cd fireblocks-mcp

• Install dependencies

npm install

• Build the project:

npm run build

Available Scripts

• npm run dev - Start development server with auto-reload
• npm run build - Build the project
• npm run test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run lint - Run ESLint
• npm run format - Format code with Prettier
• npm run inspector - Run with MCP Inspector for debugging

Testing

Run the test suite:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

Contributing

For more detailed contribution guidelines, see CONTRIBUTING.md.