Uranium MCP Server

<!-- BADGES:START -->

🚀 Quick Install

<img src="https://img.shields.io/badge/VS_Code-0098FF?style=flat-square&logo=visual-studio-code&logoColor=white" alt="Install in VS Code"> <img src="https://img.shields.io/badge/VS_Code_Insiders-24bfa5?style=flat-square&logo=visual-studio-code&logoColor=white" alt="Install in VS Code Insiders"> <img src="https://img.shields.io/badge/Cursor-000000?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTggMEMzLjU4IDAgMCAzLjU4IDAgOFMzLjU4IDE2IDggMTZTMTYgMTIuNDIgMTYgOFMxMi40MiAwIDggMFpNOCAxNEM0LjY5IDE0IDIgMTEuMzEgMiA4UzQuNjkgMiA4IDJDOC41NSAyIDkuMDggMi4wOSA5LjU4IDIuMjRMOCA0TDEyIDhMOCAxMlY5TDUgMTJWNEw4IDdWNEw5LjU4IDIuMjRDMTIuODQgMy4yNCAxNSA1LjQgMTUgOEMxNSAxMS4zMSAxMS4zMSAxNCA4IDE0WiIgZmlsbD0id2hpdGUiLz4KPC9zdmc+" alt="Install in Cursor"> <img src="https://img.shields.io/badge/Goose-FFA500?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTggMEMzLjU4IDAgMCAzLjU4IDAgOFMzLjU4IDE2IDggMTZTMTYgMTIuNDIgMTYgOFMxMi40MiAwIDggMFoiIGZpbGw9IndoaXRlIi8+Cjwvc3ZnPg==" alt="Install in Goose"> <img src="https://img.shields.io/badge/LM_Studio-7B68EE?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTggMEwxNiA0VjEyTDggMTZMMCAxMlY0TDggMFoiIGZpbGw9IndoaXRlIi8+Cjwvc3ZnPg==" alt="Install in LM Studio"> <!-- BADGES:END -->

A Model Context Protocol (MCP) server for working with portal.uranium.pro - creating and managing NFT collections and assets. This server enables LLMs to interact with blockchain NFTs through a simple, structured interface.

Key Features

• Fast and efficient NFT management. Direct integration with Uranium API for instant operations.
• Multi-collection support. Manage ERC721 and ERC1155 NFT collections seamlessly.
• File-based asset creation. Upload images, videos, audio, and documents directly as NFTs.
• Bulk operations. List and filter assets across multiple collections with pagination.

Requirements

• Node.js 18 or newer
• Uranium API key from portal.uranium.pro
• VS Code, Cursor, Windsurf, Claude Desktop, Goose or any other MCP client

<!-- // Generate using: node utils/generate-readme.js -->

Getting Started

First, install the Uranium MCP server with your client.

Standard config works in most of the tools:

{
  "mcpServers": {
    "uranium": {
      "command": "npx",
      "args": ["uranium-tools-mcp@latest"],
      "env": {
        "URANIUM_API_KEY": "your_api_key_here"
      }
    }
  }
}

<details> <summary>Claude Code</summary>

Use the Claude Code CLI to add the Uranium MCP server:

claude mcp add uranium npx uranium-tools-mcp@latest

Then set your URANIUM_API_KEY when prompted. </details>

<details> <summary>Claude Desktop</summary>

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "uranium": {
      "command": "npx",
      "args": ["uranium-tools-mcp@latest"],
      "env": {
        "URANIUM_API_KEY": "your_api_key_here"
      }
    }
  }
}

</details>

<details> <summary>Codex</summary>

Create or edit the configuration file ~/.codex/config.toml and add:

[mcp_servers.uranium]
command = "npx"
args = ["uranium-tools-mcp@latest"]
env = { URANIUM_API_KEY = "your_api_key_here" }

For more information, see the Codex MCP documentation. </details>

<details> <summary>Cursor</summary>

Click the button to install:

<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">

Or install manually:

Go to Cursor Settings -> MCP -> Add new MCP Server. Name it "uranium", use command type with the command npx uranium-tools-mcp@latest. Add environment variable URANIUM_API_KEY with your API key.

</details>

<details> <summary>Gemini CLI</summary>

Follow the MCP install guide, use the standard config above with your API key.

</details>

<details> <summary>Goose</summary>

Click the button to install:

Or install manually:

Go to Advanced settings -> Extensions -> Add custom extension. Name it "uranium", use type STDIO, and set the command to npx uranium-tools-mcp@latest. Add environment variable URANIUM_API_KEY with your API key. Click "Add Extension". </details>

<details> <summary>LM Studio</summary>

Click the button to install:

Or install manually:

Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config above with your API key. </details>

<details> <summary>opencode</summary>

Follow the MCP Servers documentation. For example in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "uranium": {
      "type": "local",
      "command": [
        "npx",
        "uranium-tools-mcp@latest"
      ],
      "env": {
        "URANIUM_API_KEY": "your_api_key_here"
      },
      "enabled": true
    }
  }
}

</details>

<details> <summary>Qodo Gen</summary>

Open Qodo Gen chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above with your API key.

Click Save. </details>

<details> <summary>VS Code</summary>

Click the button to install:

<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code"> <img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">

Or install manually:

Follow the MCP install guide, use the standard config above. You can also install the Uranium MCP server using the VS Code CLI:

# For VS Code
code --add-mcp '{"name":"uranium","command":"npx","args":["uranium-tools-mcp@latest"],"env":{"URANIUM_API_KEY":"your_api_key_here"}}'

After installation, the Uranium MCP server will be available for use with your GitHub Copilot agent in VS Code. </details>

<details> <summary>Windsurf</summary>

Follow Windsurf MCP documentation. Use the standard config above with your API key.

</details>

Configuration

Environment Variables

• URANIUM_API_KEY (required): Your Uranium API key from portal.uranium.pro
• URANIUM_BASE_URL (optional): API base URL. Defaults to https://gw.urnm.pro

Example Configuration

{
  "mcpServers": {
    "uranium": {
      "command": "npx",
      "args": ["uranium-tools-mcp@latest"],
      "env": {
        "URANIUM_API_KEY": "your_api_key_here"
        // URANIUM_BASE_URL is optional, defaults to https://gw.urnm.pro
      }
    }
  }
}

Local Installation

If you prefer to install locally:

npm install -g uranium-tools-mcp
# or
pnpm add -g uranium-tools-mcp
# or
yarn global add uranium-tools-mcp

Then use uranium-tools-mcp instead of npx uranium-tools-mcp@latest in the configuration.

Tools

<!--- Tools generated by utils/generate-tools-docs.js -->

This MCP server provides 4 main tools for NFT management:

<details> <summary><b>Collection Management</b></summary>

list_collections

• Description: List all user collections (personal, common, and external)
• Parameters: None

create_collection

• Description: Create a new NFT collection
• Parameters:
  • name (string, required): Collection name (3-30 characters, letters, numbers, and [_.-] symbols) [min length: 3, max length: 30]
  • symbol (string, required): Collection symbol (3-30 characters, letters, numbers, and underscores) [min length: 3, max length: 30]
  • type (string, enum: ERC721, ERC1155, required): Collection type: ERC721 (single NFTs) or ERC1155 (multi-token)

</details>

<details> <summary><b>Asset Management</b></summary>

list_assets

• Description: List assets with optional filtering by collection, search, and pagination
• Parameters:
  • contractId (string, optional): Filter assets by collection ID
  • page (number, optional): Page number (default: 1) [min: 1, default: 1]
  • pageSize (number, optional): Number of assets per page (default: 20, max: 100) [min: 1, max: 100, default: 20]
  • sortBy (string, optional): Sort field (default: createdAt) [default: "createdAt"]
  • order (string, enum: asc, desc, optional): Sort order (default: asc) [default: "asc"]
  • quickFilter (string, optional): Search text to filter assets by title

create_asset

• Description: Create a new NFT asset from a local file or base64 data
• Parameters:
  • filePath (string, optional): Absolute path to the media file (for local files)
  • fileData (string, optional): Base64 encoded file data (for Claude Desktop)
  • fileName (string, optional): Original filename (required when using fileData)
  • mimeType (string, optional): MIME type of the file (required when using fileData, e.g., 'image/png')
  • contractId (string, required): ID of the collection to mint the asset in
  • title (string, required): Asset title (3-120 characters) [min length: 3, max length: 120]
  • description (string, optional): Asset description (optional, max 255 characters) [max length: 255]
  • location (string, optional): Location where the asset was created (optional, max 100 characters) [max length: 100]
  • editions (number, optional): Number of editions (for ERC1155 collections only, 1-1000) [min: 1, max: 1000]
  • shareWithCommunity (boolean, optional): Make the asset discoverable by the community (optional, default: false) [default: false]

</details>

<!--- End of tools generated section -->

Supported File Formats

• Images: JPG, JPEG, PNG, GIF, WebP, SVG
• Video: MP4, WebM, MOV, AVI
• Audio: MP3, WAV, OGG
• Documents: PDF, TXT

Development

Building from Source

1. Clone the repository:

git clone https://github.com/xkelxmc/uranium-mcp.git
cd uranium-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Development Commands

# Compile in watch mode
npm run dev

# Build for production
npm run build

# Start server locally
npm start

# Clean build directory
npm run clean

Testing

Using MCP Inspector

Test your MCP server with the MCP Inspector:

# For installed version
npx @modelcontextprotocol/inspector uranium-tools-mcp

# For local development
npm run build:dev
npx @modelcontextprotocol/inspector node build/index.js

Development Testing

# Test with stdio transport
npm run dev:stdio

# Test with HTTP transport
npm run dev:http

# Inspect with HTTP transport
npm run mcp:inspect

Troubleshooting

Common Issues

1. API Key not working: Make sure your API key is valid and has the necessary permissions at portal.uranium.pro

2. Connection errors: Check that the URANIUM_BASE_URL is correct (defaults to https://gw.urnm.pro)

3. File upload issues: Ensure the file path is absolute and the file exists

4. Collection creation fails: Verify that collection names and symbols follow the required format (3-30 characters, alphanumeric and underscore)

Project Structure

src/
├── api/           # Complete copy of Uranium API from Raycast
├── utils/         # Utilities for validation, formatting, etc.
├── models/        # Upload primitives for working with files
├── tools/         # MCP tools
├── server.ts      # MCP server configuration
├── index.ts       # Entry point
└── config.ts      # API and MCP configuration

License

todo

Support

For issues and questions:

• Contact support at uranium.pro