MCP (Nano Cryptocurrency) Server

A lightweight server implementation for handling Nano cryptocurrency transactions, designed specifically for AI Assistants.

Getting Started

Quick Start with NPX

The easiest way to start the server is using npx:

npx -y nano-mcp

Installation Options

1. Using npm:

npm install nano-mcp

2. Using yarn:

yarn add nano-mcp

3. Using pnpm:

pnpm add nano-mcp

Running the Server

After installation, you can start the server in several ways:

1. Using npx:

npx nano-mcp

2. Using npm scripts:

npm start

3. Direct execution:

node src/index.js

API Methods

The server supports the following JSON-RPC 2.0 methods:

Initialize Server

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {},
  "id": 1
}

Generate Wallet

{
  "jsonrpc": "2.0",
  "method": "generateWallet",
  "params": {},
  "id": 1
}

Get Balance

{
  "jsonrpc": "2.0",
  "method": "getBalance",
  "params": {
    "address": "nano_..."
  },
  "id": 1
}

Initialize Account

{
  "jsonrpc": "2.0",
  "method": "initializeAccount",
  "params": {
    "address": "nano_...",
    "privateKey": "private_key_here"
  },
  "id": 1
}

Send Transaction

{
  "jsonrpc": "2.0",
  "method": "sendTransaction",
  "params": {
    "fromAddress": "nano_...",
    "toAddress": "nano_...",
    "amountRaw": "1000000000000000000000000",
    "privateKey": "private_key_here"
  },
  "id": 1
}

Receive Pending

{
  "jsonrpc": "2.0",
  "method": "receivePending",
  "params": {
    "address": "nano_...",
    "privateKey": "private_key_here"
  },
  "id": 1
}

Client Configuration

The MCP server can be configured in various client applications. Here are some example configurations:

Claude Desktop Configuration

{
  "mcpServers": {
    "nano": {
      "command": "npx",
      "args": ["-y", "nano-mcp"],
      "env": {
        "MCP_PORT": "8080",
        "NANO_RPC_URL": "https://rpc.nano.to",
        "NANO_RPC_KEY": "your-rpc-key"
      }
    }
  }
}

Custom Configuration Examples

1. Basic Configuration:

{
  "mcpServers": {
    "nano": {
      "command": "npx",
      "args": ["-y", "nano-mcp"]
    }
  }
}

2. With Custom Port:

{
  "mcpServers": {
    "nano": {
      "command": "npx",
      "args": ["-y", "nano-mcp"],
      "env": {
        "MCP_PORT": "8080"
      }
    }
  }
}

3. With Custom RPC Node:

{
  "mcpServers": {
    "nano": {
      "command": "npx",
      "args": ["-y", "nano-mcp"],
      "env": {
        "NANO_RPC_URL": "https://your-custom-node.com",
        "NANO_RPC_KEY": "your-rpc-key"
      }
    }
  }
}

4. Complete Configuration:

{
  "mcpServers": {
    "nano": {
      "command": "npx",
      "args": ["-y", "nano-mcp"],
      "env": {
        "MCP_PORT": "8080",
        "NANO_RPC_URL": "https://rpc.nano.to",
        "NANO_RPC_KEY": "your-rpc-key",
        "NANO_REPRESENTATIVE": "nano_3qya5xpjfsbk3ndfebo9dsrj6iy6f6idmogqtn1mtzdtwnxu6rw3dz18i6xf"
      }
    }
  }
}

Getting Started with NANO

Free NANO Faucets

To get started with testing this MCP server, you can obtain free NANO (XNO) from various faucets:

1. WeNano - A location-based social wallet app where you can earn NANO through globally distributed spots
2. XNOPay Faucet - A payment processor offering free NANO
3. Nano Drop - Simple faucet for micro-fractions of NANO
4. Nanswap Faucet - Quick and easy way to get small amounts of NANO
5. Prussia Nano Faucet - Basic faucet with simple address input
6. FreeNanoFaucet - Learn about NANO while earning some

For a complete list of available faucets, visit: https://hub.nano.org/faucets

Error Handling

All errors follow JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Error description here"
  },
  "id": 1
}

Common error codes:

• -32700: Parse error
• -32600: Invalid request
• -32601: Method not found
• -32602: Invalid params
• -32603: Internal error
• -32000: Server error

API Documentation & Testing (Swagger UI)

The MCP server includes an interactive Swagger UI for API documentation and live testing.

How to Use

1. Start the server:

   • Using npx:

     npx nano-mcp
     

   • Or using npm:

     npm start
     

   • Or directly:

     node src/index.js
     

2. Open Swagger UI:

   • Visit http://localhost:8080/api-docs in your browser.
   • You will see the full API documentation and can interactively test all endpoints.

3. Try Out Methods:

   • Use the "Try it out" button in Swagger UI to send requests to the server and see live responses.

4. Swagger JSON:

   • The raw OpenAPI/Swagger JSON is available at http://localhost:8080/api-docs.json

License

MIT License

Copyright (c) 2025 Context

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.