# 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">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522uranium%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522uranium-tools-mcp%2540latest%2522%255D%252C%2522env%2522%253A%257B%2522URANIUM_API_KEY%2522%253A%2522your_api_key_here%2522%257D%257D%257D) [<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">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522uranium%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522uranium-tools-mcp%2540latest%2522%255D%252C%2522env%2522%253A%257B%2522URANIUM_API_KEY%2522%253A%2522your_api_key_here%2522%257D%257D%257D) [<img src="https://img.shields.io/badge/Cursor-000000?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTggMEMzLjU4IDAgMCAzLjU4IDAgOFMzLjU4IDE2IDggMTZTMTYgMTIuNDIgMTYgOFMxMi40MiAwIDggMFpNOCAxNEM0LjY5IDE0IDIgMTEuMzEgMiA4UzQuNjkgMiA4IDJDOC41NSAyIDkuMDggMi4wOSA5LjU4IDIuMjRMOCA0TDEyIDhMOCAxMlY5TDUgMTJWNEw4IDdWNEw5LjU4IDIuMjRDMTIuODQgMy4yNCAxNSA1LjQgMTUgOEMxNSAxMS4zMSAxMS4zMSAxNCA4IDE0WiIgZmlsbD0id2hpdGUiLz4KPC9zdmc+" alt="Install in Cursor">](cursor://anysphere.cursor-deeplink/mcp/install?name=uranium&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJ1cmFuaXVtLXRvb2xzLW1jcEBsYXRlc3QiXSwiZW52Ijp7IlVSQU5JVU1fQVBJX0tFWSI6InlvdXJfYXBpX2tleV9oZXJlIn19) [<img src="https://img.shields.io/badge/Goose-FFA500?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTggMEMzLjU4IDAgMCAzLjU4IDAgOFMzLjU4IDE2IDggMTZTMTYgMTIuNDIgMTYgOFMxMi40MiAwIDggMFoiIGZpbGw9IndoaXRlIi8+Cjwvc3ZnPg==" alt="Install in Goose">](https://block.github.io/goose/extension?cmd=npx&arg=uranium-tools-mcp%40latest&id=uranium&name=Uranium&description=MCP%20for%20Uranium%20NFT%20tools%20to%20mint%2C%20list%2C%20and%20manage%20digital%20assets%20on%20the%20permaweb.) [<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">](https://lmstudio.ai/install-mcp?name=uranium&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJ1cmFuaXVtLXRvb2xzLW1jcEBsYXRlc3QiXSwiZW52Ijp7IlVSQU5JVU1fQVBJX0tFWSI6InlvdXJfYXBpX2tleV9oZXJlIn19)
<!-- BADGES:END -->

A Model Context Protocol (MCP) server for working with [portal.uranium.pro](https://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](https://portal.uranium.pro/dashboard/profile/api-keys)
- 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:

```json
{
  "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:

```bash
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`

```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:

```toml
[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](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers).
</details>

<details>
<summary>Cursor</summary>

#### Click the button to install:

[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](cursor://anysphere.cursor-deeplink/mcp/install?name=uranium&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJ1cmFuaXVtLXRvb2xzLW1jcEBsYXRlc3QiXSwiZW52Ijp7IlVSQU5JVU1fQVBJX0tFWSI6InlvdXJfYXBpX2tleV9oZXJlIn19)

#### 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](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use the standard config above with your API key.

</details>

<details>
<summary>Goose</summary>

#### Click the button to install:

[![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=uranium-tools-mcp%40latest&id=uranium&name=Uranium&description=MCP%20for%20Uranium%20NFT%20tools%20to%20mint%2C%20list%2C%20and%20manage%20digital%20assets%20on%20the%20permaweb.)

#### 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:

[![Add MCP Server uranium to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=uranium&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJ1cmFuaXVtLXRvb2xzLW1jcEBsYXRlc3QiXSwiZW52Ijp7IlVSQU5JVU1fQVBJX0tFWSI6InlvdXJfYXBpX2tleV9oZXJlIn19)

#### 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](https://opencode.ai/docs/mcp-servers/). For example in `~/.config/opencode/opencode.json`:

```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](https://docs.qodo.ai/qodo-documentation/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">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522uranium%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522uranium-tools-mcp%2540latest%2522%255D%252C%2522env%2522%253A%257B%2522URANIUM_API_KEY%2522%253A%2522your_api_key_here%2522%257D%257D%257D) [<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">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522uranium%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522uranium-tools-mcp%2540latest%2522%255D%252C%2522env%2522%253A%257B%2522URANIUM_API_KEY%2522%253A%2522your_api_key_here%2522%257D%257D%257D)

#### Or install manually:

Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the Uranium MCP server using the VS Code CLI:

```bash
# 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](https://docs.windsurf.com/windsurf/cascade/mcp). 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](https://portal.uranium.pro/dashboard/profile/api-keys)
- **`URANIUM_BASE_URL`** (optional): API base URL. Defaults to `https://gw.urnm.pro`

#### Example Configuration

```json
{
  "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:

```bash
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:

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

2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

#### Development Commands

```bash
# 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](https://modelcontextprotocol.io/tools/inspector):

```bash
# 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

```bash
# 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](https://portal.uranium.pro/dashboard/profile/api-keys)

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](https://uranium.pro)