goldrush-mcp-server

This project provides a MCP (Model Context Protocol) server that exposes Covalent's GoldRush APIs as MCP resources and tools. It is implemented in TypeScript using @modelcontextprotocol/sdk and @covalenthq/client-sdk.

Table of Contents

• Key Features
• Getting Started
• Tools
• Resources
• Development
• Contributing
• Show your support
• License

Key Features

Model Context Protocol (MCP) is a message protocol for connecting context or tool-providing servers with LLM clients. This server allows an LLM client to:

• Call Covalent GoldRush API endpoints as MCP Tools
• Read from MCP Resources that give chain info, quote currencies, chain statuses, etc.
• Flexible Transport Support: Unified server supporting both STDIO and HTTP transports
• Command-line Interface: Easy configuration via CLI arguments
• Fully testable with Vitest for testing each group of tools.
• Modular architecture where each service is implemented as a separate module, making the codebase easier to maintain and extend.

Getting Started

GoldRush API key

Using any of the GoldRush developer tools requires an API key.

Get yours at https://goldrush.dev/platform/auth/register/

Usage with Claude Desktop

Add this to your `claude_desktop_config.json`:

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

For more details follow the official MCP Quickstart for Claude Desktop Users

Usage with Claude Code CLI

$ claude mcp add goldrush -e GOLDRUSH_API_KEY= -- npx -y @covalenthq/goldrush-mcp-server@latest

For more details see Set up Model Context Protocol (MCP)

Usage with Cursor

1. Open Cursor Settings

2. Go to Features > MCP

3. Click + Add new global MCP server

4. Add this to your `~/.cursor/mcp.json`:

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

For project specific configuration, add the above to a `.cursor/mcp.json` file in your project directory. This allows you to define MCP servers that are only available within that specific project.

After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use any MCP tools that are listed under Available Tools on the MCP settings page if it determines them to be relevant. To prompt tool usage intentionally, simply tell the agent to use the tool, referring to it either by name or by description.

See Example LLM Flow

Usage with Windsurf

Add this to your `~/.codeium/windsurf/mcp_config.json` file:

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

Programmatic Usage

The server supports both STDIO and HTTP transports for different integration scenarios:

STDIO Transport (Recommended for MCP Clients)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
    command: "npx",
    args: ["-y", "@covalenthq/goldrush-mcp-server@latest"],
    env: { GOLDRUSH_API_KEY: "your_api_key_here" },
});

const client = new Client(
    {
        name: "example-client",
        version: "1.0.0",
    },
    {
        capabilities: {
            tools: {},
        },
    }
);

await client.connect(transport);

// List tools and call them
const tools = await client.listTools();
console.log(
    "Available tools:",
    tools.tools.map((tool) => tool.name).join(", ")
);

const result = await client.callTool({
    name: "token_balances",
    arguments: {
        chainName: "eth-mainnet",
        address: "0xfC43f5F9dd45258b3AFf31Bdbe6561D97e8B71de",
        quoteCurrency: "USD",
        nft: false,
    },
});
console.log("Token balances:", result.content);

HTTP Transport (For Web Integrations)

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

Then make HTTP requests:

const response = await fetch("http://localhost:3000/mcp", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer YOUR_GOLDRUSH_API_KEY",
    },
    body: JSON.stringify({
        jsonrpc: "2.0",
        id: 1,
        method: "tools/call",
        params: {
            name: "token_balances",
            arguments: {
                chainName: "eth-mainnet",
                address: "0xfC43f5F9dd45258b3AFf31Bdbe6561D97e8B71de",
                quoteCurrency: "USD",
                nft: false,
            },
        },
    }),
});

const result = await response.json();
console.log("Token balances:", result);

Example LLM Flow

1. An LLM-based application starts.

2. It spawns or connects to this MCP server.

3. The LLM decides to call a tool like `transaction_summary` to gather data about a wallet.

4. The server calls the Covalent endpoint under the hood, returns JSON to the LLM, which then uses it in the conversation context.

Tools

Tools are a powerful primitive in the Model Context Protocol (MCP) that enable servers to expose executable functionality to clients. Through tools, LLMs can interact with external systems, perform computations, and take actions in the real world.

Tools are designed to be model-controlled, meaning that tools are exposed from servers to clients with the intention of the AI model being able to automatically invoke them (with a human in the loop to grant approval).

1. `bitcoin_hd_wallet_balances`

2. `bitcoin_non_hd_wallet_balances`

3. `bitcoin_transactions`

4. `block`

5. `block_heights`

6. `erc20_token_transfers`

7. `gas_prices`

8. `historical_portfolio_value`

9. `historical_token_balances`

10. `historical_token_prices`

11. `log_events_by_address`

12. `log_events_by_topic`

13. `multichain_address_activity`

14. `multichain_balances`

15. `multichain_transactions`

16. `native_token_balance`

17. `nft_check_ownership`

18. `nft_for_address`

19. `pool_spot_prices`

20. `token_approvals`

21. `token_balances`

22. `token_holders`

23. `transaction`

24. `transaction_summary`

25. `transactions_for_address`

26. `transactions_for_block`

Resources

Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions.

Resources are designed to be application-controlled, meaning that the client application can decide how and when they should be used. Different MCP clients may handle resources differently. For example:

• Claude Desktop currently requires users to explicitly select resources before they can be used
• Other clients might automatically select resources based on heuristics
• Some implementations may even allow the AI model itself to determine which resources to use

Resources exposed by the GoldRush MCP server are split into static and dynamic types:

• Static resources (`src/resources/staticResources.ts`):

• Dynamic resources (`src/resources/dynamicResources.ts`):

Dynamic resources fetch real-time data from the Covalent API on each request, ensuring current information.

Development

Prerequisites

• Node.js v18 or higher
• npm, yarn, or pnpm
• GOLDRUSH_API_KEY environment variable containing a valid GoldRush API key

Installation

git clone https://github.com/covalenthq/goldrush-mcp-server.git
cd goldrush-mcp-server
npm install

Then build:

npm run build

Running the MCP Server

The server supports multiple transport options:

# Start with default STDIO transport (recommended for MCP clients)
npm run start

# Or explicitly specify STDIO transport
npm run start:stdio

# Start with HTTP transport on port 3000
npm run start:http

# Custom configuration with CLI arguments
node dist/index.js --transport http --port 8080
node dist/index.js --transport stdio --api-key YOUR_KEY_HERE

Transport Options

• STDIO (default): Direct MCP protocol communication via stdin/stdout - ideal for MCP clients like Claude Desktop
• HTTP: RESTful HTTP server with `/mcp` endpoint - useful for web integrations

Command Line Arguments

• `--transport`, `-t`: Choose transport type (`stdio` or `http`)
• `--port`, `-p`: Set HTTP port (default: 3000)
• `--api-key`, `-k`: Provide API key directly
• `--help`, `-h`: Show usage information

STDIO transport spawns the MCP server on stdin/stdout where MCP clients can connect directly. HTTP transport starts a server that accepts POST requests to `/mcp` with Bearer token authentication.

Example Client

You can run the example client that will spawn the server as a child process via STDIO:

npm run example

This attempts a few Covalent calls and prints out the responses.

Running the Tests

npm run test

This runs the entire test suite covering each service.

Setting GOLDRUSH_API_KEY

You must set the `GOLDRUSH_API_KEY` environment variable to a valid key from the Covalent platform.

For example on Linux/macOS:

export GOLDRUSH_API_KEY=YOUR_KEY_HERE

Or on Windows:

set GOLDRUSH_API_KEY=YOUR_KEY_HERE

File Layout

goldrush-mcp-server
├── src
│   ├── index.ts                 # Main entry point with CLI parsing
│   ├── server.ts                # Unified server with STDIO and HTTP transports
│   ├── server-stdio.ts          # Legacy STDIO-only server (backup)
│   ├── services/                # Modular service implementations
│   │   ├── AllChainsService.ts  # Cross-chain service tools
│   │   ├── BalanceService.ts    # Balance-related tools
│   │   ├── BaseService.ts       # Basic blockchain tools
│   │   ├── BitcoinService.ts    # Bitcoin-specific tools
│   │   ├── NftService.ts        # NFT-related tools
│   │   ├── PricingService.ts    # Pricing-related tools
│   │   ├── SecurityService.ts   # Security-related tools
│   │   └── TransactionService.ts# Transaction-related tools
│   ├── resources/               # Resource implementations
│   │   ├── staticResources.ts   # Static configuration resources
│   │   └── dynamicResources.ts  # Dynamic chain status resources
│   ├── utils/                   # Utility functions and constants
│   │   ├── constants.ts         # Shared constants
│   │   └── helpers.ts           # Helper functions
│   └── example-client.ts        # Example LLM client using STDIO transport
├── test
│   ├── AllChainsService.test.ts
│   ├── BalanceService.test.ts
│   ├── BaseService.test.ts
│   ├── BitcoinService.test.ts
│   ├── NftService.test.ts
│   ├── PricingService.test.ts
│   ├── Resources.test.ts
│   ├── SecurityService.test.ts
│   └── TransactionService.test.ts
├── eslint.config.mjs            # ESLint configuration
├── package.json                 # Project dependencies and scripts
├── package-lock.json            # Locked dependencies
├── tsconfig.json                # TypeScript configuration
├── LICENSE                      # MIT license
└── README.md                    # Project documentation

Debugging

Using Inspector

https://modelcontextprotocol.io/docs/tools/inspector

npx @modelcontextprotocol/inspector node dist/index.js

Contributing

We welcome contributions from the community! If you have suggestions, improvements, or new spam contract addresses to add, please open an issue or submit a pull request. Feel free to check page.

Show your support

Give a ⭐️ if this project helped you!

License

This project is licensed.