MCP server

What is OpenSea MCP?

OpenSea MCP is a hosted server that gives AI tools secure access to blockchain data across NFTs, tokens, and wallets. Query real-time prices, swap tokens, analyze portfolios, and mint NFTs, all through natural language. It works with popular AI assistants like ChatGPT, Cursor, Claude, and Chorus.

Why use OpenSea MCP?

• Easy setup: Connect through a simple URL configuration
• Real-time data: Access live prices for NFTs, tokens, and cryptocurrencies
• Broad blockchain coverage: Support for Ethereum, Polygon, Base, Solana and other major chains
• Built for AI: Efficient data formatting and keyword search designed for AI agents

What can you do with OpenSea MCP?

• Analyze tokens and cryptocurrencies: Look up ERC-20 tokens, meme coins, and get real-time price data
• Swap tokens: Get quotes and transaction data for token swaps across supported chains
• Research NFT collections: Get floor prices, volume data, and trending collections
• Check wallet portfolios: View complete holdings including NFTs, tokens, and balances for any address
• Track market trends: Identify trending tokens, NFT collections, and monitor trading activity
• Mint NFTs from drops: Get drop details, check eligibility, and generate mint transactions
• Deploy NFT contracts: Deploy new SeaDrop NFT contracts and track deployment status
• Discover AI agent tools: Search the onchain Tool Registry (ERC-8257) for registered tools and check their access requirements

Getting Started

Connect through your AI tool

To connect OpenSea MCP to your AI assistant, use one of these connection methods. You can start with only the URL for the handshake, tool discovery, and get_instant_api_key. Add the API key before calling data tools.

Streamable HTTP (Recommended)

• URL: https://mcp.opensea.io/mcp
• JSON config:

{
    "mcpServers": {
      "OpenSea": {
        "url": "https://mcp.opensea.io/mcp"
      }
    }
}

SSE (Server-Sent Events)

• URL: https://mcp.opensea.io/sse
• JSON config:

{
    "mcpServers": {
      "OpenSea": {
        "url": "https://mcp.opensea.io/sse"
      }
    }
}

Providing your API key

You can present your OpenSea API key in whichever way your client supports:

• X-API-KEY header (shown below): recommended.
• Authorization: Bearer YOUR_API_KEY header: use this if your client only supports bearer-token auth (for example, Perplexity's connector). The same OpenSea API key is accepted here.

The same OpenSea API key works for both the REST API and MCP. There is no separate MCP token.

For an API-key-only client, add it to the connection headers:

{
  "url": "https://mcp.opensea.io/mcp",
  "headers": { "X-API-KEY": "YOUR_API_KEY" }
}

OAuth wallet authentication

Standard clients discover OAuth from
https://mcp.opensea.io/.well-known/oauth-protected-resource, open the OpenSea
wallet sign-in flow, and send the resulting JWT in Authorization: Bearer.
A wallet JWT does not replace the API key. Send the API key in X-API-KEY and
the wallet JWT in Authorization: Bearer when calling wallet-scoped tools.
Wallet tools enforce the scopes advertised by the protected-resource metadata.

MCP receives the short-lived wallet JWT, not the scoped PAT. A server-side agent that controls a signing key can use the manual SIWE and PAT flow, exchange the PAT for a JWT, and send that JWT in Authorization: Bearer.

If a data tool reports that an API key is missing, create or supply a key, add it as X-API-KEY, and reconnect. The MCP handshake and tools/list work without a key, but until a valid key is sent tools/list returns only get_instant_api_key.

Quick Start Examples

Once connected, try these prompts to explore OpenSea MCP capabilities:

1. "What's the price of PEPE token on Ethereum?"
2. "Show me trending tokens on Base"
3. "Quote a swap of 1 ETH to USDC"
4. "Check the complete portfolio for wallet 0x123..."
5. "What's the floor price of Pudgy Penguins?"
6. "Find the top meme coins by trading volume"

Sample Project

Prefer a working app? Try the Next.js + Vercel AI SDK starter preconfigured with OpenSea MCP:
https://github.com/ProjectOpenSea/opensea-mcp-next-sample

Supported Tools

Now that you have installed the OpenSea MCP, let's explore how AI assistants can use OpenSea MCP tools to search, analyze, and interact with blockchain and marketplace data.

These tools work together through prompts, and they are most useful in combination. With a single prompt, you can search for collections, check token prices, analyze wallet holdings, and get swap quotes across multiple blockchains.

Common Use Cases

Token Trading:

"Get a quote to swap 0.5 ETH for USDC on Base, then show me the transaction data"

Token Discovery:

"Find trending meme coins on Solana and show their 24-hour price changes"

Portfolio Analysis:

"Show me all tokens and NFTs owned by vitalik.eth with current USD values"

Market Research:

"What are the top tokens by trading volume on Ethereum today?"

NFT Research:

"Find NFT collections trending in the last 24 hours with floor price under 1 ETH"

NFT Minting:

"Check if I'm eligible for the upcoming drop and prepare the mint transaction for 2 NFTs"

Tool Discovery (ERC-8257):

"Search for NFT-gated AI tools on Base and show what each one requires for access"

Chain Support

OpenSea MCP supports all of the blockchains supported on the OpenSea web front-end.

When using tools, you can specify the chain parameter to filter results to a specific blockchain.

Best Practices

1. Name the type in searches - Search is keyword-routed, so include a type word (token, NFT, account) and a chain name in the query
2. Combine tools - Get comprehensive insights by using multiple tools together
3. Specify chains - When looking for specific blockchain data, include the chain name
4. Check balances first - Before requesting swap quotes, verify wallet has sufficient tokens
5. Use collection slugs - For specific collections, use their OpenSea slug (e.g., 'boredapeyachtclub')
6. Use includes for extra data - get_collections, get_items, and get_profile take an optional includes array, for example recent_sales or top_holders for collections, active_offers for items, and listings for a profile
7. Specify amounts correctly - For swap quotes, fromQuantity must be an integer in the token's base units (wei for ETH, lamports for SOL); decimal amounts like 0.001 are rejected

Rate Limits and Performance

• Most queries return results within 1-3 seconds
• Rate limits apply per API key
• Use pagination for large result sets
• Cursor-based pagination available for trending and top collections/tokens

Error Handling

The MCP server provides clear error messages:

• Invalid addresses or contract addresses
• Unsupported chains
• Rate limit exceeded
• Insufficient token balance for swaps

For questions, feedback or support, contact [email protected].

Client setup

Claude

Claude supports remote MCP connectors in its web and desktop apps. On a Pro or Max plan:

1. Open Customize > Connectors, click + Add, then Add custom connector.
2. Name it OpenSea and set the URL to https://mcp.opensea.io/mcp.
3. Under Request headers, add X-API-KEY with your OpenSea API key. Without it, Claude can list only get_instant_api_key.
4. Keep sign-in enabled if you want the wallet tools, and complete the OpenSea wallet sign-in when Claude asks. Otherwise choose No sign in.

On Team and Enterprise plans, an owner adds the connector under Organization settings > Connectors first.

For Claude's hosted remote connector, you do not need to edit Claude Desktop's local JSON file.
See Claude's custom connector guide for current availability and setup details.

Cursor

Go to Cursor Settings > MCP > Add new global MCP server, or edit the file directly:

• Project-level: .cursor/mcp.json in your project root
• Global: ~/.cursor/mcp.json

Add the JSON config above. For API-key access, use the header example from
Providing your API key. If Cursor offers an
authentication action after discovering OpenSea OAuth, complete it to add your
wallet identity. The OpenSea server should then show a green status indicator in
Cursor Settings > MCP.

VS Code (GitHub Copilot)

Run MCP: Open User Configuration from the Command Palette to edit your user mcp.json, or create .vscode/mcp.json in your workspace, and add:

{
  "servers": {
    "OpenSea": {
      "type": "http",
      "url": "https://mcp.opensea.io/mcp",
      "headers": {
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}

Open Copilot Chat, switch to Agent mode, and click the tools icon to confirm the OpenSea tools are available.

Windsurf

Go to Windsurf Settings > Cascade > MCP, or edit ~/.codeium/windsurf/mcp_config.json. Note: Windsurf uses serverUrl instead of url:

{
  "mcpServers": {
    "OpenSea": {
      "serverUrl": "https://mcp.opensea.io/mcp",
      "headers": {
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}

ChatGPT

ChatGPT treats custom MCP connectors as apps:

1. Enable developer mode for your account or workspace.
2. Go to Settings > Apps > Create.
3. Add an app named OpenSea with the endpoint https://mcp.opensea.io/mcp.
4. Choose OAuth when testing wallet authentication, then select Scan tools.
5. Complete the OpenSea wallet sign-in and create the app.

Full MCP support is currently limited by plan and workspace settings. See
OpenAI's developer mode guide
for the current requirements.

Perplexity

An organization admin must first allow custom remote connectors:

1. Go to Account settings > Connectors.
2. Select Custom connector > Remote.
3. Name the connector OpenSea and set its URL to https://mcp.opensea.io/mcp.
4. Choose Streamable HTTP as the transport.
5. Choose API Key for data-only testing or OAuth for wallet authentication.
6. Add the connector, open its card, and complete authentication.

Perplexity presents API Key and OAuth as separate authentication methods. Check
the two-credential requirement before testing a
wallet-scoped tool. See
Perplexity's remote connector guide
for organization controls and current setup details.

Check your connection

Test each client in a new conversation:

1. Confirm the OpenSea tools appear.
2. Call a data tool, such as asking for a token price, to verify the API key.
3. Call get_favorites to verify OAuth wallet identity and the
   read:favorites scope.
4. If the client reports a missing API key after OAuth, it is not sending both
   required credentials. Recheck its custom-header support.

When reporting a problem, include the client, plan, model, authentication
method, tool name, and exact error. Remove API keys, wallet JWTs, and other
secrets before sharing logs.

Custom Applications

Integrate OpenSea MCP into your own applications using any MCP-compatible SDK:

Vercel AI SDK: See the full starter project at opensea-mcp-next-sample. The MCP client ships in the @ai-sdk/mcp package (npm install @ai-sdk/mcp).

import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";

const apiKey = process.env.OPENSEA_API_KEY;
if (!apiKey) throw new Error("OPENSEA_API_KEY is required");

const mcpClient = await createMCPClient({
  transport: {
    type: "sse",
    url: "https://mcp.opensea.io/sse",
    headers: { "X-API-KEY": apiKey },
  },
});
const tools = await mcpClient.tools();

Python

This uses the mcp package 2.x, which takes headers through an httpx2 client:

import httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async with httpx2.AsyncClient(headers={"X-API-KEY": "YOUR_API_KEY"}) as http_client:
    async with streamable_http_client(
        "https://mcp.opensea.io/mcp", http_client=http_client
    ) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.opensea.io/mcp"),
  { requestInit: { headers: { "X-API-KEY": "YOUR_API_KEY" } } }
);
const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);
const { tools } = await client.listTools();