GoldRush MCP Server

How to use

Choose your transport method and connect your MCP client. You can run the server locally and interact with it either through STDIO (recommended for embedded clients) or via HTTP for web integrations.

How to install

Prerequisites: install a recent Node.js (v18 or higher) and a modern package manager (npm, yarn, or pnpm). You also need a valid GoldRush API key.

# 1) Clone the project
git clone https://github.com/covalenthq/goldrush-mcp-server.git
cd goldrush-mcp-server

# 2) Install dependencies
npm install

# 3) Build the project
npm run build

Set your API key in the environment before starting the server.

export GOLDRUSH_API_KEY=YOUR_API_KEY_HERE
# On Windows use: set GOLDRUSH_API_KEY=YOUR_API_KEY_HERE

Start the server using STDIO transport (default) or HTTP transport if you want an HTTP endpoint.

Additional configuration and usage notes

You can configure clients to connect using either STDIO or HTTP. The STDIO flow starts a child process that communicates via stdin and stdout, while the HTTP flow exposes a REST endpoint at /mcp to receive JSON-RPC style requests.

Configuration examples

{
  "mcpServers": {
    "goldrush": {
      "command": "npx",
      "args": ["-y", "@covalenthq/goldrush-mcp-server@latest"],
      "env": {
        "GOLDRUSH_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

# Start the HTTP server on port 3000
node dist/index.js --transport http --port 3000

If you want to connect via STDIO, run the same package via a CLI tool as shown in the examples and let your MCP client manage the transport layer.

Example client interactions

You can list available tools and call a specific tool using your MCP client. The server exposes Covalent GoldRush tools such as token balances, block data, NFT data, and more. Use your client to request a tool by name and pass the appropriate arguments for your use case.

Troubleshooting

If the server does not respond, ensure the GOLDRUSH_API_KEY is set correctly and that the server process started without errors. Check that the HTTP port is not blocked by a firewall and that your MCP client is pointed at the correct transport (STDIO or HTTP) and endpoint.

Security considerations

Protect your API key and restrict access to the HTTP endpoint to trusted clients. When using STDIO, ensure the host process that runs the MCP client is secure and that only authorized components can communicate with the server.

Project structure overview

The server is implemented in TypeScript and supports modular services for balance, transactions, NFTs, pricing, and more. It includes both static and dynamic MCP resources, with dynamic resources fetching real-time data from Covalent on each request.

Example LLM flow

An LLM-based application starts and connects to the MCP server. It uses tools like transaction_summary or token_balances to gather data, which is then returned to the model to inform the conversation. The server handles the data fetch from Covalent and returns structured results suitable for context.

Development

Prerequisites include Node.js v18+, npm/yarn/pnpm, and a valid API key. Build and run steps are provided to enable rapid experimentation during development.

bitcoin_hd_wallet_balances

Fetch balances for each active child address derived from a Bitcoin HD wallet, providing total, available balances, and transaction history.

bitcoin_non_hd_wallet_balances

Fetch Bitcoin balance for a non-HD address with optional price conversion and metadata.

bitcoin_transactions

Fetch transactions for a Bitcoin address with pagination and full details.

block

Fetch and render a single block for a block explorer, given chain and height.

block_heights

Retrieve block heights within a date range with optional pagination.

erc20_token_transfers

Render token transfer events for an address or token, with optional price quotes and filters.

gas_prices

Get real-time gas estimates for different transaction speeds on a network.

historical_portfolio_value

Render daily portfolio value for an address across a timeframe.

historical_token_balances

Fetch historical token balances for an address at a specific block or date.

historical_token_prices

Get historical prices for a token over a date range.

log_events_by_address

Decode and return event logs for a contract address within a block range.

log_events_by_topic

Decode logs for a specific topic hash across contracts on a chain.

multichain_address_activity

Summarize wallet activity across supported blockchains.

multichain_balances

Get token balances across multiple blockchains for a wallet.

multichain_transactions

Fetch transactions for multiple addresses across multiple blockchains.

native_token_balance

Get the native token balance for a wallet on a specific chain.

nft_check_ownership

Verify NFT ownership for a wallet within a collection.

nft_for_address

List all NFTs owned by a wallet on a chain.

pool_spot_prices

Get spot prices for a pool contract across Uniswap variants.

token_approvals

List token approvals for a wallet across contracts with risk data.

token_balances

Fetch native and ERC20 token balances for a wallet.

token_holders

Paginated list of current or historical holders for a token.

transaction

Fetch a single transaction with optional internal/state/input data details.

transaction_summary

Fetch earliest/latest transactions and count for a wallet.

transactions_for_address

Fetch recent transactions involving a wallet.

transactions_for_block

Fetch all transactions in a block with optional logs.