Setup

The Phantom MCP server (@phantom/mcp-server) enables AI assistants like Claude to interact with Phantom embedded wallets through natural language. AI agents can view wallet addresses, sign transactions, transfer tokens, swap tokens, trade perpetual futures on Hyperliquid, and rebalance portfolios across Solana, Ethereum, Bitcoin, and Sui.

This MCP server is currently in preview and may change at any time without notice. Always use a separate Phantom account specifically for testing with AI agents. Phantom makes no guarantees around anything your agent may do using this MCP server. Never use accounts containing significant assets.

Looking for the MCP server that gives your AI coding assistant access to Phantom developer documentation? See the Phantom Connect SDK MCP server documentation.

Features

SSO authentication: Seamless integration with Phantom’s embedded wallet SSO flow (Google/Apple login).
Session persistence: Automatic session management with stamper keys stored locally.
Multi-chain support: Works with Solana, Ethereum, Bitcoin, and Sui networks.
Twenty-five MCP tools:
- get_connection_status: Check local wallet connection status.
- get_wallet_addresses: Get blockchain addresses for the authenticated embedded wallet.
- get_token_balances: Get token holdings with live USD pricing.
- send_solana_transaction: Sign and broadcast Solana transactions.
- send_evm_transaction: Sign and broadcast EVM transactions with automatic gas estimation.
- sign_solana_message: Sign UTF-8 messages on Solana.
- sign_evm_personal_message: EIP-191 personal message signing for EVM.
- sign_evm_typed_data: EIP-712 structured data signing.
- transfer_tokens: Transfer native tokens and SPL/ERC-20 tokens across Solana and EVM.
- buy_token: Fetch a swap quote from the Phantom routing engine for Solana, EVM, and cross-chain swaps with optional execution.
- phantom_login: Re-authenticate, switch accounts, or refresh an expired session.
- pay_api_access: Pay for daily API access when quota is consumed.
- portfolio_rebalance: Analyze portfolio allocation and rebalance via token swaps.
- deposit_to_hyperliquid: Bridge tokens from external chains into Hyperliquid as USDC.
- transfer_spot_to_perps: Move USDC from Hyperliquid spot account to perps account.
- withdraw_from_perps: Move USDC from perps account back to spot.
- get_perp_account: Get perps account balance and withdrawable amount.
- get_perp_markets: List available perpetual markets with prices, funding rates, and leverage limits.
- get_perp_positions: Get open positions with PnL and liquidation prices.
- get_perp_orders: Get open orders (limit, take-profit, stop-loss).
- get_perp_trade_history: Get historical perpetual trades.
- open_perp_position: Open long or short positions with market or limit orders.
- close_perp_position: Close full or partial perpetual positions.
- cancel_perp_order: Cancel an open perpetual order.
- update_perp_leverage: Update leverage and margin type for a market.

Prerequisites

Before using the MCP server, you need an App ID from Phantom Portal.

Visit Phantom Portal

Go to phantom.com/portal and sign in with your Google or Apple account.

Create an app

Select Create App and fill in the required details.

Configure redirect URL

Navigate to Dashboard > View App > Redirect URLs and add http://localhost:8080/callback as a redirect URL. This allows the OAuth callback to work correctly.

Get your App ID

Navigate to the Phantom Connect tab to find your App ID. Copy it for the MCP server configuration.

The email you use to sign in to Phantom Portal must match the email you use when authenticating in the MCP server. If these don’t match, authentication will fail.

Installation

Option 1: npx (recommended)

Use npx to run the server without global installation. This ensures you always use the latest version:

npx -y @phantom/mcp-server

Option 2: Global install

Install the package globally for faster startup:

npm install -g @phantom/mcp-server

Then run:

phantom-mcp

Setup guides

Claude Desktop
Cursor
Claude Code

Add the MCP server to your Claude Desktop configuration file.Configuration file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Using npx (recommended):

{
  "mcpServers": {
    "phantom": {
      "command": "npx",
      "args": ["-y", "@phantom/mcp-server"],
      "env": {
        "PHANTOM_APP_ID": "your_app_id_from_portal"
      }
    }
  }
}

Using global install:

{
  "mcpServers": {
    "phantom": {
      "command": "phantom-mcp",
      "env": {
        "PHANTOM_APP_ID": "your_app_id_from_portal"
      }
    }
  }
}

After updating the config, restart Claude Desktop to load the server.

Option 1: Cursor plugin (recommended)

Install the Phantom Cursor plugin for the best experience. It includes this MCP server plus subagents, skills, and rules for building with Phantom. See the Cursor plugin documentation for details.

Option 2: Manual setup

Add the MCP server to your Cursor configuration at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "phantom": {
      "command": "npx",
      "args": ["-y", "@phantom/mcp-server"],
      "env": {
        "PHANTOM_APP_ID": "your_app_id_from_portal"
      }
    }
  }
}

After saving, restart Cursor to load the server.See the Cursor MCP documentation for more details.

Run the following command to add the MCP server:

claude mcp add phantom -- npx -y @phantom/mcp-server

Set the required environment variable:

export PHANTOM_APP_ID=your_app_id_from_portal

Verify the installation:

claude mcp list

See the Claude Code documentation for more details.

Environment variables

Configure the server behavior using environment variables.

Required

Variable	Description
`PHANTOM_APP_ID` / `PHANTOM_CLIENT_ID`	Your App ID from Phantom Portal

Optional

Variable	Description	Default
`PHANTOM_CLIENT_SECRET`	Client secret for confidential clients	—
`PHANTOM_CALLBACK_PORT`	OAuth callback port	`8080`
`PHANTOM_CALLBACK_PATH`	OAuth callback path	`/callback`
`PHANTOM_MCP_DEBUG`	Enable debug logging (set to `1`)	—
`PHANTOM_AUTH_BASE_URL`	Override the auth base URL	—
`PHANTOM_CONNECT_BASE_URL`	Override the Connect base URL	—
`PHANTOM_API_BASE_URL`	Override the API base URL	—
`PHANTOM_QUOTES_API_URL`	Override the quotes API URL	—

Client types

Public client (recommended): Provide only PHANTOM_APP_ID. Uses PKCE for security, similar to the browser SDK.
Confidential client: Provide both PHANTOM_APP_ID and PHANTOM_CLIENT_SECRET. Uses HTTP Basic Auth + PKCE.

Authentication flow

On first run, the server will:

Use the App ID from the PHANTOM_APP_ID environment variable.
Open your default browser to https://connect.phantom.app for Google/Apple login.
Start a local server on port 8080 to receive the SSO callback.
Save your session to ~/.phantom-mcp/session.json.

Sessions use stamper keys which don’t expire. The embedded wallet is created during SSO authentication and persists across sessions.

Tool reference

Parameters and examples for all 25 tools

Session management

Sessions are stored in ~/.phantom-mcp/session.json and contain wallet and organization identifiers, stamper keys, and user authentication details. Sessions persist indefinitely until explicitly deleted. To reset your session, run:

rm ~/.phantom-mcp/session.json

Then restart your AI assistant. The server will re-authenticate on next use.

Security

PKCE: Uses Proof Key for Code Exchange for secure OAuth authentication.
Session security: Session files have restrictive Unix permissions (user-only read/write).
Request signing: API key stamper prevents request tampering.
HTTPS: All API requests use HTTPS.
Ephemeral binding: Callback server uses ephemeral localhost binding.

Testing

Test the server directly using the MCP inspector:

npx @modelcontextprotocol/inspector npx -y @phantom/mcp-server

This opens an interactive web UI where you can test tool calls without an AI assistant.

Troubleshooting

Browser doesn't open during authentication

Ensure you have a default browser configured.
Manually visit the URL shown in the logs.
Check if the open command works in your terminal: open https://phantom.app.

Port 8080 already in use

The OAuth callback server cannot bind to port 8080.Solutions:

Stop the process using port 8080: lsof -ti:8080 | xargs kill.
Change the callback port by setting PHANTOM_CALLBACK_PORT to a different value, then update the redirect URL in Phantom Portal to match (e.g., http://localhost:9090/callback).

Authentication email mismatch

Authentication fails when the email used for Phantom Portal doesn’t match the email used during MCP server authentication.Solution: Use the same email address for both Phantom Portal sign-in and MCP server authentication (Google/Apple login).

Session not persisting

The server asks you to authenticate every time.Solutions:

Check session file exists: ls -la ~/.phantom-mcp/session.json.
Verify file permissions: chmod 600 ~/.phantom-mcp/session.json.
Ensure ~/.phantom-mcp directory has correct permissions: chmod 700 ~/.phantom-mcp.

MCP server not loading in Claude Desktop

Claude Desktop doesn’t show the Phantom tools.Solutions:

Verify the config file contains valid JSON.
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/.
- Windows: %APPDATA%/Claude/logs/.
Restart Claude Desktop after config changes.
Test the server manually with the MCP inspector (see the Testing section).

Invalid session error

Session exists but is rejected by the API.Solutions:

Verify your App ID is correct in Phantom Portal.
Ensure the authentication email matches the Phantom Portal email.
Delete the session file: rm ~/.phantom-mcp/session.json.
Restart your AI assistant and re-authenticate when prompted.

Phantom Cursor plugin

All-in-one Cursor plugin with subagents, skills, rules, and both MCP servers

Phantom Connect SDK MCP server

Get accurate Phantom developer guidance in your AI coding assistant

Phantom Portal

Set up your app and get your App ID

SDK overview

Choose the right SDK for your application

Developer support

Contact the Phantom developer support team

Overview

Setup and reference

Features

Prerequisites

Installation

Option 1: npx (recommended)

Option 2: Global install

Setup guides

Option 1: Cursor plugin (recommended)

Option 2: Manual setup

Environment variables

Required

Optional

Client types

Authentication flow

Tool reference

Session management

Security

Testing

Troubleshooting

Phantom Cursor plugin

Phantom Connect SDK MCP server

Phantom Portal

SDK overview

Developer support

Overview

Setup and reference

​Features

​Prerequisites

​Installation

​Option 1: npx (recommended)

​Option 2: Global install

​Setup guides

​Option 1: Cursor plugin (recommended)

​Option 2: Manual setup

​Environment variables

​Required

​Optional

​Client types

​Authentication flow

Tool reference

​Session management

​Security

​Testing

​Troubleshooting

​Related resources

Phantom Cursor plugin

Phantom Connect SDK MCP server

Phantom Portal

SDK overview

Developer support

Features

Prerequisites

Installation

Option 1: npx (recommended)

Option 2: Global install

Setup guides

Option 1: Cursor plugin (recommended)

Option 2: Manual setup

Environment variables

Required

Optional

Client types

Authentication flow

Session management

Security

Testing

Troubleshooting

Related resources