Skip to main content
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, rebalance portfolios, and trade perps across Solana, Ethereum, Bitcoin, and Sui.
Always use a separate Phantom account for testing with AI agents. Phantom makes no guarantees around anything your agent may do using this MCP server. Transactions are irreversible. 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

  • Device-code authentication: Browser-based Phantom sign-in with device authorization. No App ID or Phantom Portal setup required.
  • Dedicated agent wallets: Each agent gets its own wallet on authentication — separate from your personal wallet.
  • Session persistence: Automatic session management with stamper keys stored in ~/.phantom-mcp/session.json.
  • Auto re-authentication: On session expiry (401/403), the server automatically triggers re-auth and retries the tool call.
  • Multi-chain support: Works with Solana, Ethereum, Bitcoin, and Sui networks.
  • Simulation-first wallet flows:
    • send_solana_transaction, send_evm_transaction, and transfer_tokens can preview asset changes and warnings before submitting.
  • 28 wallet, swap, and perp tools. See the tool reference for full parameter documentation.
    • Wallet: get_connection_status, get_wallet_addresses, get_token_balances, transfer_tokens, send_solana_transaction, send_evm_transaction, sign_solana_message, sign_evm_personal_message, sign_evm_typed_data, simulate_transaction, get_token_allowance, phantom_login, pay_api_access.
    • Swaps: buy_token (Solana, EVM, and cross-chain, no fees), portfolio_rebalance (no fees).
    • Perps: get_perp_markets, get_perp_account, get_perp_positions, get_perp_orders, get_perp_trade_history, deposit_to_hyperliquid, open_perp_position, close_perp_position, cancel_perp_order, update_perp_leverage, transfer_spot_to_perps, withdraw_from_perps, withdraw_from_hyperliquid_spot.

​
Installation

Use npx to run the server without global installation. This ensures you always use the latest version: 
npx -y @phantom/mcp-server@latest

​
Option 2: Global install

Install the package globally for faster startup: 
npm install -g @phantom/mcp-server@latest
Then run: 
phantom-mcp

​
Setup guides

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@latest"]
    }
  }
}
Using global install:
{
  "mcpServers": {
    "phantom": {
      "command": "phantom-mcp"
    }
  }
}
After updating the config, restart Claude Desktop to load the server.

​
Environment variables

Most users do not need to set any environment variables. The following optional variables are available for advanced use:
VariableDescriptionDefault
PHANTOM_MCP_DEBUGEnable debug logging (set to 1 or true)—
PHANTOM_AUTH_BASE_URLOverride the Phantom auth base URL—
PHANTOM_CONNECT_BASE_URLOverride the Phantom Connect base URL—
PHANTOM_WALLETS_API_BASE_URLOverride the Phantom wallets/KMS API base URL—
PHANTOM_API_BASE_URLOverride the Phantom API base URL—
PHANTOM_VERSIONOverride the version header sent with requests—
ENABLE_FILE_LOGGINGEnable file-based logging—

​
Authentication flow

On first run, the server will:
  1. Start Phantom’s device authorization flow.
  2. Open your default browser so you can sign in with Google or Apple and approve the wallet session.
  3. Save your session to ~/.phantom-mcp/session.json.
Sessions persist across restarts until they are deleted or rejected server-side, at which point the MCP server automatically triggers re-authentication.

Tool reference

Parameters and examples for the current toolset

​
Agent wallets

Agents receive a new dedicated wallet when they authenticate — they do not connect to your existing personal wallet.
If you previously used @phantom/mcp-server version 0.2.4 or earlier, the wallet model has changed:
  • Existing prompts or workflows that assumed access to your personal wallet may no longer behave the same way.
  • Newly authenticated agents must be funded before they can transfer tokens, swap, or perform other on-chain actions.
  • Use get_wallet_addresses after authenticating to check the agent’s wallet address, then send funds to that address before attempting transactions.

​
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

  • Device-code authentication: Secure browser-based sign-in flow with no local callback server.
  • Session security: Session files have restrictive Unix permissions (user-only read/write, 0o600).
  • Request signing: OIDC stamper signs KMS requests to prevent tampering.
  • HTTPS: All API requests use HTTPS.

​
Testing

Test the server directly using the MCP inspector: 
npx @modelcontextprotocol/inspector npx -y @phantom/mcp-server@latest
This opens an interactive web UI where you can test tool calls without an AI assistant.

​
Troubleshooting

  • 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.
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.
Claude Desktop doesn’t show the Phantom tools.Solutions:
  1. Verify the config file contains valid JSON.
  2. Check Claude Desktop logs:
    • macOS: ~/Library/Logs/Claude/.
    • Windows: %APPDATA%/Claude/logs/.
  3. Restart Claude Desktop after config changes.
  4. Test the server manually with the MCP inspector (see the Testing section).
Session exists but is rejected by the API.Solutions:
  • 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

Manage your apps and SDK configuration

SDK overview

Choose the right SDK for your application

Developer support

Contact the Phantom developer support team