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

# Setup

> Install and configure the Phantom MCP Server for Claude Desktop, Cursor, and Claude Code

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.

<Info>
  Looking for the MCP server that gives your AI coding assistant access to Phantom developer documentation? See the [Phantom Connect SDK MCP server](/resources/mcp-server) documentation.
</Info>

## 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.
* 27 wallet, swap, and perp tools. See the [tool reference](/phantom-mcp-server/tools) 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`.

## Installation

### Option 1: npx (recommended)

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

```bash theme={null}
npx -y @phantom/mcp-server@latest
```

### Option 2: Global install

Install the package globally for faster startup:

```bash theme={null}
npm install -g @phantom/mcp-server@latest
```

Then run:

```bash theme={null}
phantom-mcp
```

## Setup guides

<Tabs>
  <Tab title="Claude Desktop">
    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):

    ```json theme={null}
    {
      "mcpServers": {
        "phantom": {
          "command": "npx",
          "args": ["-y", "@phantom/mcp-server@latest"]
        }
      }
    }
    ```

    Using global install:

    ```json theme={null}
    {
      "mcpServers": {
        "phantom": {
          "command": "phantom-mcp"
        }
      }
    }
    ```

    After updating the config, restart Claude Desktop to load the server.
  </Tab>

  <Tab title="Cursor">
    ### Option 1: Cursor plugin (recommended)

    Install the [Phantom Cursor plugin](https://cursor.com/marketplace/phantom) for the best experience. It includes this MCP server plus subagents, skills, and rules for building with Phantom. See the [Cursor plugin documentation](/resources/cursor-plugin) for details.

    ### Option 2: Manual setup

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

    ```json theme={null}
    {
      "mcpServers": {
        "phantom": {
          "command": "npx",
          "args": ["-y", "@phantom/mcp-server@latest"]
        }
      }
    }
    ```

    After saving, restart Cursor to load the server.

    See the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) for more details.
  </Tab>

  <Tab title="Claude Code">
    Run the following command to add the MCP server:

    ```bash theme={null}
    claude mcp add phantom -- npx -y @phantom/mcp-server@latest
    ```

    Verify the installation:

    ```bash theme={null}
    claude mcp list
    ```

    See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details.
  </Tab>
</Tabs>

## Environment variables

Most users do not need to set any environment variables. The following optional variables are available for advanced use:

| Variable                       | Description                                    | Default |
| ------------------------------ | ---------------------------------------------- | ------- |
| `PHANTOM_MCP_DEBUG`            | Enable debug logging (set to `1` or `true`)    | —       |
| `PHANTOM_AUTH_BASE_URL`        | Override the Phantom auth base URL             | —       |
| `PHANTOM_CONNECT_BASE_URL`     | Override the Phantom Connect base URL          | —       |
| `PHANTOM_WALLETS_API_BASE_URL` | Override the Phantom wallets/KMS API base URL  | —       |
| `PHANTOM_API_BASE_URL`         | Override the Phantom API base URL              | —       |
| `PHANTOM_VERSION`              | Override the version header sent with requests | —       |
| `ENABLE_FILE_LOGGING`          | Enable 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.

<Card title="Tool reference" icon="book" href="/phantom-mcp-server/tools">
  Parameters and examples for the current toolset
</Card>

## Agent wallets

<Warning>
  Agents receive a **new dedicated wallet** when they authenticate — they do not connect to your existing personal wallet.
</Warning>

<Card title="Agent wallets and your existing accounts" icon="users" href="/phantom-mcp-server/account-types">
  Why your agent gets a new wallet when you sign in, and how to access your existing Phantom accounts.
</Card>

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:

```bash theme={null}
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:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="MCP server not loading in Claude Desktop">
    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).
  </Accordion>

  <Accordion title="Invalid session error">
    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.
  </Accordion>
</AccordionGroup>

## Related resources

<CardGroup cols={2}>
  <Card title="Phantom Cursor plugin" icon="puzzle-piece" href="/resources/cursor-plugin">
    All-in-one Cursor plugin with subagents, skills, rules, and both MCP servers
  </Card>

  <Card title="Phantom Connect SDK MCP server" icon="server" href="/resources/mcp-server">
    Get accurate Phantom developer guidance in your AI coding assistant
  </Card>

  <Card title="Phantom Portal" icon="browser" href="/phantom-portal/portal">
    Manage your apps and SDK configuration
  </Card>

  <Card title="SDK overview" icon="code" href="/wallet-sdks-overview">
    Choose the right SDK for your application
  </Card>

  <Card title="Developer support" icon="life-ring" href="https://docs.google.com/forms/d/e/1FAIpQLSeHWETFkEJbHQCF-lnl1AHmVQPuyfC0HbnxjDjIp6VYV1sBZQ/viewform">
    Contact the Phantom developer support team
  </Card>
</CardGroup>