How to Using Rarible Protocol MCP
This guide covers three key ways to get started with the @rarible/protocol-mcp
SDK: integrating with Claude, integrating with ChatGPT, self-hosting the MCP server, and leveraging the OpenAPI specification for custom integrations.
Prerequisites
- Node.js: Version 20 or higher.
- Rarible API Key: Obtain from https://rarible.org/pricing.
- Environment Setup: Set the API key as an environment variable:
export RARIBLE_API_KEY="your-api-key-here"
- Tools: Familiarity with TypeScript/JavaScript, terminal commands, and optionally Postman or OpenAPI Generator.
Quick Start: Claude Integration
Integrate the SDK with Claude/OpenAI to enable AI-driven interactions using the MCP server.
Installation
Install the SDK:
npm install @rarible/protocol-mcp
Or use pnpm
, bun
, or yarn
:
pnpm add @rarible/protocol-mcp
bun add @rarible/protocol-mcp
yarn add @rarible/protocol-mcp zod
Configure Claude
- Update Config:
Add the MCP server toclaude_desktop_config.json
:{ "mcpServers": { "RaribleProtocolMcp": { "command": "npx", "args": [ "-y", "--package", "@rarible/protocol-mcp", "--", "mcp", "start", "--api-key-auth", "your-api-key-here" ] } } }
- Restart Claude
Usage
- In Claude, use queries like "Fetch NFT details for ID ETHEREUM:0x..." or "Get collection floor price."
- Claude maps these to SDK methods (e.g.,
nftItems.getItemById
) and returns formatted results.
Troubleshooting
- Verify API key and Node.js version (
node -v
). - Check Claude logs for errors like
UnionApiErrorBadRequest
.
ChatGPT Integration
Integrate the SDK with ChatGPT using OpenAI's MCP support to enable AI-driven interactions.
Prerequisites
- OpenAI API Key: Obtain from https://platform.openai.com/api-keys
- MCP Server: A publicly accessible MCP server endpoint (see Self-Hosting section below)
- Rarible API Key: Set on your MCP server
Setup
- Deploy MCP Server: Ensure your MCP server is running and accessible via HTTPS
- Configure ChatGPT: Use the OpenAI API with MCP tools configuration
Usage Example
Use the OpenAI API with MCP tools to interact with Rarible Protocol:
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
-d '{
"model": "o4-mini-2025-04-16",
"tools": [
{
"type": "mcp",
"server_label": "rarible-protocol",
"server_url": "https://your-mcp-server.com/sse",
"require_approval": "never"
}
],
"input": "please find NFT tokens for the owner ETHEREUM:0x28e0A9154Ed24988f30B743b5F3Cf060CC4234C0"
}'
Configuration Parameters
model
: Use compatible OpenAI models (e.g.,o4-mini-2025-04-16
)server_label
: Identifier for your MCP serverserver_url
: Public HTTPS endpoint of your MCP serverrequire_approval
: Set to"never"
for automatic tool execution
Common Use Cases
- NFT Discovery: "Find NFTs owned by address ETHEREUM:0x..."
- Collection Analysis: "Get floor price for collection X"
- Market Data: "Show recent sales for NFT Y"
- Ownership Queries: "List all collections owned by address Z"
Troubleshooting
- 401 Unauthorized: Verify your OpenAI API key
- MCP Server Errors: Ensure your server is publicly accessible and HTTPS-enabled
- Rate Limits: Handle OpenAI API rate limits according to your plan
- Tool Execution: Check MCP server logs for Rarible API errors
Self-Hosting Quick Start
Run the SDK as a local or cloud-hosted MCP server for direct API access.
Installation
-
Create Project:
mkdir rarible-mcp-server cd rarible-mcp-server npm init -y npm install @rarible/protocol-mcp
-
Start Server:
npx -y --package @rarible/protocol-mcp -- mcp start --api-key-auth $RARIBLE_API_KEY --protocol sse
-
Optional: Customize:
Change port or add options:npx -y --package @rarible/protocol-mcp -- mcp start --api-key-auth $RARIBLE_API_KEY --port 8080 --protocol sse
Test the Server
- Run MCP server locally
npx -y --package @rarible/protocol-mcp -- mcp start --api-key-auth $RARIBLE_API_KEY --port 8080 --protocol sse
- Run MCP inspector:
npx @modelcontextprotocol/inspector
- Connect to mcp server an run tools:
SDK Integration
- Install SDK:
npm install @rarible/protocol-mcp
- Example Usage:
import { RaribleProtocolMcp } from "@rarible/protocol-mcp"; const sdk = new RaribleProtocolMcp({ apiKeyAuth: process.env.RARIBLE_API_KEY || "your-api-key-here", }); async function run() { const result = await sdk.nftItems.getItemById({ itemId: "ETHEREUM:0xb66a603f4cfe17e3d27b87a8bfcad319856518b8:32292934596187112148346015918544186536963932779440027682601542850818403729410", }); console.log(result); } run();
Custom HTTP Client
- Customize requests:
import { HTTPClient } from "@rarible/protocol-mcp/lib/http"; const httpClient = new HTTPClient({ fetcher: fetch }); httpClient.addHook("beforeRequest", (request) => { request.headers.set("x-custom-header", "custom-value"); return request; }); const sdk = new RaribleProtocolMcp({ httpClient, apiKeyAuth: "your-api-key-here" });
Troubleshooting
- Verify API key permissions and spec version.
- Handle rate limits (
429
errors) per Rarible's documentation.
Next Steps
- Explore Rarible Protocol documentation for advanced features.
Updated about 21 hours ago