> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GoldRush MCP Server

> A server that exposes GoldRush APIs as MCP resources and tools, enabling LLMs to interact with blockchain data.

The GoldRush MCP Server provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) implementation that exposes GoldRush APIs as MCP resources and tools. It enables LLMs to interact with blockchain data across multiple chains.

One connector gives you **37 tools**: 28 blockchain data tools covering balances, transactions, NFTs, prices and approvals, plus 9 protocol analytics tools covering volume, fees, TVL, liquidations and active users.

> [!NOTE]
>
> You'll need a GoldRush API key to use this server.

> [card] [Get Started](https://goldrush.dev/platform/auth/register/?plan=vibe)
>
> Sign up for \$10/mo - perfect for AI-native builders using Claude, Cursor, or Windsurf.

## Setup Instructions

### Step 1: Installation

No installation is needed. The server is hosted at `https://mcp.goldrushdata.com/mcp`. There is nothing to clone and no config file to edit unless your client requires one.

### Step 2: Add the connector

**1. Claude: add from the connector directory**

GoldRush is listed in [Claude's connector directory](https://claude.ai/directory/aa8cfef6-cb23-4f4f-928d-6cb90ff4e1e8) as a community connector. This is the shortest path and it works on both Claude.ai and Claude Desktop.

1. Go to **Customize > Connectors**.
2. Find **GoldRush** in the directory and click **Connect**.
3. Paste your GoldRush API key on the sign-in page.

The connector authenticates over OAuth, and the API key you paste is the credential it carries. You still need a GoldRush API key.

**2. Claude: add as a custom connector (fallback)**

Use this only if the directory listing is unavailable in your Claude build.

1. Go to **Customize > Connectors** and click **Add custom connector**.
2. Enter `https://mcp.goldrushdata.com/mcp`. If asked for an **OAuth client**, choose **Register automatically**.
3. Click **Add**, then paste your GoldRush API key on the sign-in page.

For more details, see [Add a connector that isn't in the directory](https://claude.com/docs/connectors/custom/remote-mcp).

**3. Usage with Claude Code CLI**

```bash theme={null}
$ claude mcp add --transport http goldrush https://mcp.goldrushdata.com/mcp --header "Authorization: Bearer <GOLDRUSH_API_KEY>"
```

For more details, see [Set up Model Context Protocol (MCP)](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp).

**4. 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`:

```json theme={null}
{
  "mcpServers": {
    "goldrush": {
      "url": "https://mcp.goldrushdata.com/mcp",
      "headers": {
        "Authorization": "Bearer <GOLDRUSH_API_KEY>"
      }
    }
  }
}   
```

For project-specific configuration, add the above to a `.cursor/mcp.json` file in your project directory.

**5. Usage with Windsurf**

Add this to your `mcp_config.json` file:

```json theme={null}
{
  "mcpServers": {
    "goldrush": {
      "serverUrl": "https://mcp.goldrushdata.com/mcp",
      "headers": {
        "Authorization": "Bearer <GOLDRUSH_API_KEY>"
      }
    }
  }
}   
```

**6. Any other MCP client**

The server is a standard remote MCP server over streamable HTTP. Any client that supports remote MCP servers can connect with two values:

* **URL**: `https://mcp.goldrushdata.com/mcp`
* **Auth**: either the `Authorization: Bearer <GOLDRUSH_API_KEY>` header, or the OAuth flow if your client registers an OAuth client automatically.

Follow your client's own instructions for adding a remote MCP server or custom connector.

### Step 3: Programmatic Usage

Here's an example using the MCP TypeScript SDK:

```typescript theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.goldrushdata.com/mcp"),
  { requestInit: { headers: { Authorization: "Bearer <GOLDRUSH_API_KEY>" } } }
);

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

await client.connect(transport);

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

// Now you can call tools
const result = await client.callTool({
  name: "getAllChains",
  arguments: {}
});

console.log(result);
```

## Available Tools

The GoldRush MCP Server exposes **37 tools**. The 28 blockchain data tools below are the full set; the 9 protocol analytics tools are listed in the next section.

> [accordion] Cross Chain
>
> * **multichain\_address\_activity**: Gets a summary of wallet activity across all supported blockchains.
> * **multichain\_balances**: Gets token balances for a wallet address across multiple blockchains.
> * **multichain\_transactions**: Gets transactions for multiple wallet addresses across multiple blockchains.

> [accordion] Balances
>
> * **token\_balances**: Commonly used to fetch the native and fungible (ERC20) tokens held by an address.
> * **historical\_token\_balances**: Commonly used to fetch the historical native and fungible (ERC20) tokens held by an address at a given block height or date.
> * **native\_token\_balance**: Get the native token balance (ETH, BNB, MATIC, etc.) for a specified wallet address on a blockchain.
> * **erc20\_token\_transfers**: Commonly used to render the transfer-in and transfer-out of a token along with historical prices from an address.
> * **historical\_portfolio\_value**: Commonly used to render a daily portfolio balance for an address broken down by the token.
> * **token\_holders**: Used to get a paginated list of current or historical token holders for a specified ERC20 or ERC721 token.

> [accordion] Transaction
>
> * **transaction**: Commonly used to fetch and render a single transaction including its decoded log events.
> * **transaction\_summary**: Commonly used to fetch the earliest and latest transactions, and the transaction count for a wallet.
> * **transactions\_for\_address**: Commonly used to fetch and render the most recent transactions involving an address.
> * **transactions\_for\_block**: Commonly used to fetch all transactions including their decoded log events in a block and further flag interesting wallets or transactions.

> [accordion] NFT
>
> * **nft\_for\_address**: Commonly used to get all NFTs owned by a specific wallet address on a blockchain.
> * **nft\_check\_ownership**: Commonly used to verify ownership of NFTs (including ERC-721 and ERC-1155) within a collection.
> * **nft\_check\_ownership\_token\_id**: Verifies ownership of a specific token (ERC-721 or ERC-1155) within a collection.

> [accordion] Security
>
> * **token\_approvals**: Commonly used to get a list of approvals across all token contracts categorized by spenders for a wallet's assets.

> [accordion] Bitcoin
>
> * **bitcoin\_hd\_wallet\_balances**: Fetch balances for each active child address derived from a Bitcoin HD wallet.
> * **bitcoin\_non\_hd\_wallet\_balances**: Fetch Bitcoin balance for a non-HD address.
> * **bitcoin\_transactions**: Fetch transactions for a specific Bitcoin address with full transaction details.

> [accordion] Prices
>
> * **historical\_token\_prices**: Commonly used to get historic prices of a token between date ranges.
> * **pool\_spot\_prices**: Get the spot token pair prices for a specified pool contract address. Supports pools on Uniswap V2, V3 and their forks.
> * **gas\_prices**: Get real-time gas estimates for different transaction speeds on a specific network.

> [accordion] Utility
>
> * **log\_events\_by\_address**: Commonly used to get all the event logs emitted from a particular contract address.
> * **log\_events\_by\_topic**: Commonly used to get all event logs of the same topic hash across all contracts within a particular chain.
> * **block**: Commonly used to fetch and render a single block for a block explorer.
> * **block\_heights**: Commonly used to get all the block heights within a particular date range.
> * **resolve\_address**: Resolves ENS, RNS and Unstoppable Domains addresses. Only supports the resolution of a registered domain to an address.

Every tool's parameters and their descriptions are served by the connector itself. Call `tools/list` over MCP, or open your client's tool inspector, for the authoritative, always-current schema.

## Protocol Analytics Tools

Nine of the 37 tools answer protocol-level analytics questions (volume, fees, TVL, liquidations, active users) rather than fetching a single address or transaction. They run over a semantic layer, and the set of datasets they can reach is discovered at runtime, so start with `list_entities` or `search_catalog` rather than guessing a dataset name.

> [accordion] Discovery
>
> * **list\_entities**: The complete list of datasets with live analytics, each with its metric ids, concepts, breakdown and filter dimensions, depth and semantic quality. Anything not listed here cannot be queried.
> * **search\_catalog**: Typed, fuzzy keyword search across every entity, metric, concept and dimension. Use it first when a question names a dataset, provider, measure or ticker you have not confirmed exists. Each match carries the next call to make.
> * **get\_metadata**: Everything about one dataset: what each metric means, which breakdowns and filters it supports, its coverage and caveats, and an explicit statement of what it cannot answer.

> [accordion] Members
>
> * **list\_members**: The values a dimension holds (chains, markets, builder codes, coins, tickers, deployers), ranked and searchable, with the exact strings to pass back as filters. Values are matched exactly and case-sensitively.

> [accordion] Analytics
>
> * **get\_metric**: One metric of one dataset as a day, week or month series, with a summary of the window.
> * **get\_metrics**: Several metrics of one dataset in a single call, each independently executed with its own success or no-data state.
> * **get\_breakdown**: Split one metric by a dimension it supports (chain, asset, market), with each member's share when a total is meaningful.
> * **compare\_entities**: Compare exactly the 2 to 10 datasets you name, on one metric, with a leader. No other dataset is ever added.
> * **rank\_entities**: Rank every eligible protocol that serves a metric, without naming them. The server discovers the candidates and checks comparability.

> [!NOTE]
>
> **These tools refuse rather than approximate.** If a comparison is not semantically valid, for example Aave against Morpho on liquidations, the tools return a structured refusal explaining why the comparison does not hold instead of a number that looks right and is not. Refusals are final: `incomparable_metrics`, `metric_not_available`, `unsupported` and `requires_breakdown` will not be worked around by rephrasing the question. Follow the `next_actions` in the response instead. Windows end on the last complete UTC day, and a null bucket means missing data, never zero.

## Available Resources

Resources are a core primitive in the Model Context Protocol that allow servers to expose data and content for use as context in LLM interactions. The GoldRush MCP Server provides both static and dynamic resources:

> [accordion] Static Resources
>
> * **config://supported-chains**: The chain names the connector's tools accept
> * **config://quote-currencies**: Provides a list of all supported quote currencies for price conversions

> [accordion] Dynamic Resources
>
> * **status\://all-chains**: Provides real-time synchronization status for all chains
> * **status\://chain/{chainName}**: Provides detailed status information for a specific chain

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

## Chains the Connector Accepts

The `chainName` parameter on every blockchain data tool is a fixed enum, so the connector reaches a narrower set of chains than the [Foundational API](https://goldrush.dev/docs/goldrush-foundational-api/overview.md) does. It currently accepts **65 chain names, 44 of them mainnets**. `config://supported-chains` serves exactly that list, and reading it is the reliable way to check whether a chain is callable through MCP. A chain that the REST API supports but that is absent from that resource cannot be requested through the connector.

## Example LLM Interaction

Once you've set up the GoldRush MCP Server with your preferred LLM client, you can start asking blockchain-related questions:

* "What are the top tokens in this Ethereum wallet: 0xeefB13C7D42eFCc655E528dA6d6F7bBcf9A2251d?"
* "Show me the transaction history for this wallet address on Polygon."
* "What NFTs does this wallet own across multiple chains?"
* "Get the gas prices for ERC20 transfers on Ethereum mainnet."

The protocol analytics tools answer a different shape of question:

* "Which protocols have the highest fees over the last 30 days?"
* "Break down Hyperliquid volume by market for the last week."
* "What datasets do you have live analytics for?"

The LLM will automatically use the appropriate GoldRush MCP tools to retrieve the blockchain data and provide you with informative responses.

## Related Resources

* **[GoldRush Agent Skills](https://goldrush.dev/docs/goldrush-agent-skills/overview.md)** — Install skills for AI agents (Claude, Cursor, Gemini)
* **[GoldRush SDKs & CLI](https://goldrush.dev/docs/goldrush-sdks.md)** — TypeScript, Python, and CLI tools
* **[Powered by GoldRush](https://goldrush.dev/docs/powered-by-goldrush.md)** — See how projects use our APIs
* **[What is GoldRush](https://goldrush.dev/docs/overview.md)** — Learn about all GoldRush products


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.