io.github.fyllepo/qubic-mcp

Install

Config snippet generator goes here (5 client tabs)

README

<p align="center">
  <img src="assets/qubic-logo.png" alt="Qubic" width="300">
</p>

# qubic-mcp

> MCP server for the Qubic cryptocurrency — enabling AI assistants to interact with the Qubic network.

[![npm version](https://img.shields.io/npm/v/mcp-server-qubic)](https://www.npmjs.com/package/mcp-server-qubic)
[![CI](https://github.com/fyllepo/qubic-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/fyllepo/qubic-mcp/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

## Overview

**qubic-mcp** is an open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI assistants — Claude, ChatGPT, Copilot, Cursor, and others — native access to the [Qubic](https://qubic.org) blockchain.

Query balances, inspect transactions, monitor the network, trade on QX, switch between networks, and interact with smart contracts — all through natural language.

## What's New in v0.4

- **Smart Contract Profiles** — Register custom SC interface definitions, then query them by name with automatic binary encoding/decoding
- **Network Management** — Save and switch between mainnet, testnet, or your own local/lite node at runtime
- **Epoch Computors** — Query the 676 computor identities for any epoch
- **MCP Prompts** — Predefined workflows for portfolio analysis, market overview, and research
- **MCP Resources** — Qubic reference documentation (network, tokenomics, smart contracts, address format)
- **HTTP Transport** — Run as a standalone HTTP server for remote deployment

## Features

### Blockchain Query Tools

- **Balance & Transfers** — Query any Qubic address balance and transfer history
- **Transactions** — Look up transaction details by ID
- **Network Status** — Current tick, epoch, supply, burned QUs, active addresses, market cap
- **Mining Phase** — Current MINING/IDLE phase, cycle progress, and XMR marathon status
- **Epoch Computors** — List all 676 computor identities for a given epoch
- **Rich List** — Top holders ranked by balance

### Market & Analytics

- **Token Price** — Real-time QUBIC price compared across 3 sources (CoinGecko, Qubic API, CryptoCompare)
- **QU/USD Converter** — Convert between QU and USD at live rates
- **Token Registry** — List all registered Qubic tokens with issuer and website
- **QX DEX Orderbook** — Live ask/bid orders for any token on the QX decentralized exchange

### Smart Contract Tools

- **Register Contract** — Save a custom SC interface definition (function names, input/output field schemas)
- **Query Contract** — Query a registered SC function by name with automatic binary encoding/decoding
- **Raw SC Query** — Low-level smart contract query with base64 input/output for advanced use
- **List/Remove Contracts** — Manage your registered contract definitions

### Local Management

- **Wallet Management** — Save wallet addresses locally for quick access
- **Network Switching** — Save and switch between mainnet, testnet, or custom RPC endpoints at runtime
- **Address Validation** — Check format and on-chain activity
- **Explorer Links** — Direct links to the official Qubic block explorer

### AI Context

- **MCP Resources** — Qubic reference docs (network, tokenomics, smart contracts, address format) available as context
- **MCP Prompts** — Predefined workflows: portfolio analysis, market overview, and Qubic research

## Quick Start

Works with any MCP-compatible AI client — Claude, ChatGPT, Copilot, Cursor, Windsurf, Gemini, JetBrains, and more.

Add this to your client's MCP config:

```json
{
  "mcpServers": {
    "qubic": {
      "command": "npx",
      "args": ["mcp-server-qubic"]
    }
  }
}
```

<details>
<summary>Where to find the config file</summary>

| Client | Config location |
|--------|----------------|
| **Claude Desktop** (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Claude Desktop** (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Claude Desktop** (Linux) | `~/.config/Claude/claude_desktop_config.json` |
| **Claude Code** | Run `claude mcp add qubic -- npx mcp-server-qubic` in your terminal |
| **VS Code / Cursor / Windsurf** | `.vscode/mcp.json` or your editor's MCP settings |
| **JetBrains IDEs** | Settings > Tools > AI Assistant > MCP Servers |
| **ChatGPT Desktop** | Settings > MCP Servers > Add |

For other clients, check your app's MCP documentation — the config above is universal.

</details>

Then just ask in plain English:

### Wallet Management

```
"Save my wallet UXITJAGNXUE...RAPDBE as my-main"
"List my wallets"
"Remove my old-wallet"
```

### Balances & Transfers

```
"What's the balance of my-main?"
"Show transfer history for my-main over the last 1000 ticks"
```

### Price & Market

```
"What's the current QUBIC price?"
"How much is 1 billion QU worth in USD?"
"Convert $100 to QU"
```

### Network & Mining

```
"What's the current