MCP 服务器

Nimiq MCP Server

A Model Context Protocol (MCP) server for interacting with the Nimiq blockchain.

README

<h1 align="center"> <img alt="Nimiq MCP Server logo" loading="lazy" width="96" height="96" decoding="async" data-nimg="1" style="color:transparent" src="https://raw.githubusercontent.com/onmax/nimiq-mcp/refs/heads/main/.github/logo.svg" /> Nimiq MCP Server</h1> A Model Context Protocol (MCP) server for interacting with the Nimiq blockchain.

<a href="https://modelcontextprotocol.io"> 📖 Model Context Protocol </a>

Features

🚀 Two deployment options: Zero-setup remote access OR local installation
🔗 18 comprehensive tools for accounts, transactions, blocks, validators, and more
🤖 MCP 2025-06-18 Protocol: Latest specification with enhanced features
💬 Interactive Tools: Elicitation support for guided user experiences
⚡ Remote option: No installation required - just add the URL to your MCP client
🔧 Local option: Full control with npx nimiq-mcp
🔍 Advanced search: Full-text search through comprehensive Nimiq documentation
📊 Enhanced calculations: Interactive staking rewards calculator with smart defaults
🔒 Read-only operations (sending transactions not supported for security)
✅ Input validation: Comprehensive schema validation for all tool inputs

Quick Start

Choose one of two options:

Option 1: Remote Access

Add this to your MCP client configuration:

{
  "mcpServers": {
    "nimiq": {
      "url": "https://nimiq-mcp.je-cf9.workers.dev/sse",
      "transport": "sse"
    }
  }
}

Option 2: Local Installation

Add this to your MCP client configuration:

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

Comparison

Feature	Remote Access	Local Installation
Setup	Zero installation required	Requires Node.js/npm
Updates	Automatic	Manual (npx pulls latest)
Privacy	Requests go through our servers	Direct connection to RPC
Availability	Depends on our service uptime	Depends on local environment
Protocol Support	SSE transport only	Full MCP protocol support

With Custom RPC Endpoint & Auth

<details> <summary>Remote (SSE)</summary>

{
  "mcpServers": {
    "nimiq": {
      "url": "https://nimiq-mcp.je-cf9.workers.dev/sse?rpc-url=https://your-rpc-endpoint.com&rpc-username=your-username&rpc-password=your-password",
      "transport": "sse"
    }
  }
}

</details>

<details> <summary>Local (npx)</summary>

{
  "mcpServers": {
    "nimiq": {
      "command": "npx",
      "args": [
        "nimiq-mcp",
        "--rpc-url",
        "https://your-rpc-endpoint.com",
        "--rpc-username",
        "your-username",
        "--rpc-password",
        "your-password"
      ]
    }
  }
}

</details>

Available Arguments

CLI Arguments	URL Arguments	Description	Default
`--rpc-url <url>`	`rpc-url=<url>`	Nimiq RPC endpoint URL	`https://rpc.nimiqwatch.com`
`--rpc-username <username>`	`rpc-username=<username>`	RPC username for authentication	None
`--rpc-password <password>`	`rpc-password=<password>`	RPC password for authentication	None
`--help, -h`	N/A	Show help message	N/A

Available Tools and Resources

The MCP server provides comprehensive tools and resources for interacting with the Nimiq blockchain:

Tools (18 available)

Category	Tool	Description
Blockchain Data Tools	`getHead`	Get the current head block of the Nimiq blockchain
	`getBlockByNumber`	Retrieve a specific block by its number
	`getBlockByHash`	Retrieve a specific block by its hash
	`getEpochNumber`	Get the current epoch number
Blockchain Calculation Tools	`getSupply`	Get the current circulating supply of NIM
	`calculateSupplyAt`	Calculate the Nimiq PoS supply at a given time
	`calculateStakingRewards`	Calculates the potential wealth accumulation based on staking
	`interactiveStakingCalculator`	NEW: Interactive calculator with elicitation support
	`getPrice`	Get the price of NIM against other currencies
Account & Balance Tools	`getAccount`	Get detailed account information by address
	`getBalance`	Get the balance of a specific account address
Transaction Tools	`getTransaction`	Get detailed transaction information by hash
	`getTransactionsByAddress`	Get transaction history for a specific address
Validator Tools	`getValidators`	Get information about all active validators
	`getValidator`	Get detailed information about a specific validator
	`getSlots`	Get validator slot information for current or specific block
Network Tools	`getNetworkInfo`	Get network status including peer count and consensus state
Documentation Tools	`getRpcMethods`	Get all available RPC methods from the latest OpenRPC document
	`searchDocs`	Search through the Nimiq documentation using full-text search

Resources (3 available)

Category	Resource	Description
Documentation Resources	`nimiq://docs/web-client`	Complete web-client documentation for LLMs
	`nimiq://docs/protocol`	Complete Nimiq protocol and learning documentation for LLMs
	`nimiq://docs/validators`	Complete validator and staking documentation for LLMs

Tool Parameters

Each tool accepts specific parameters:

Block tools: includeBody (boolean) to include transaction details
Address tools: address (string) for Nimiq addresses
Transaction tools: hash (string) for transaction hashes, max (number) for limits
Documentation tools: includeSchemas (boolean) for getRpcMethods to include detailed parameter/result schemas
Search tools: query (string) for search terms, limit (number) to control result count

Resource Access

Resources are accessed via their URI and don't require parameters:

Documentation resources: Access via nimiq://docs/web-client, nimiq://docs/protocol, or nimiq://docs/validators
Content is returned as plain text for optimal LLM consumption
MCP clients can cache resource content for improved performance

Example Responses

Supply Data Response

{
  "total": 210000000000000,
  "vested": 0,
  "burned": 0,
  "max": 210000000000000,
  "initial": 25200000000000,
  "staking": 100000000000,
  "minted": 1000000000,
  "circulating": 25200000000000,
  "mined": 0,
  "updatedAt": "2025-01-20T12:00:00.000Z"
}

Block Data Response

{
  "blockNumber": 21076071,
  "block": {
    "hash": "90e2ba0a831eec477bca1a26ba8c5e2b3162b5d042667828c4db0f735247d41e",
    "number": 21076071,
    "timestamp": 1749486768481,
    "parentHash": "b4fae3fc846ac13bfc62aa502c8683e25e92616d987f3f642b9cb57da73b6392",
    "type": "micro",
    "producer": {
      "slotNumber": 305,
      "validator": "NQ51 LM8E Q8LS 53TX GGDG 26M4 VX4Y XRE2 8JDT"
    }
  },
  "timestamp": "2025-06-09T16:32:49.055Z",
  "network": "mainnet"
}

Search Documentation Response

{
  "query": "validator staking",
  "totalResults": 3,
  "results": [
    {
      "title": "Validator Setup",
      "content": "To become a validator in Nimiq, you need to stake NIM tokens...",
      "section": "Validators",
      "score": 0.95,
      "snippet": "...validator in Nimiq, you need to stake NIM tokens and run validator software..."
    },
    {
      "title": "Staking Rewards",
      "content": "Validators earn rewards for producing blocks and validating transactions...",
      "section": "Economics",
      "score": 0.87,
      "snippet": "...earn rewards for producing blocks and validating transactions. Staking rewards..."
    }
  ],
  "searchedAt": "2025-01-20T12:00:00.000Z"
}

Usage Examples

Claude Desktop Configuration

Option 1: Remote (Zero Setup)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nimiq": {
      "url": "https://nimiq-mcp.je-cf9.workers.dev/sse",
      "transport": "sse"
    }
  }
}

Option 2: Local Installation

Add to your claude_desktop_config.json:

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

With Custom Local Configuration

{
  "mcpServers": {
    "nimiq": {
      "command": "npx",
      "args": [
        "nimiq-mcp",
        "--rpc-url",
        "https://rpc.nimiqwatch.com"
      ]
    }
  }
}

In Web Applications

Access the remote server directly via HTTP:

// Connect to the remote MCP server
const mcpClient = new SSEClientTransport(
  new URL('https://nimiq-mcp.je-cf9.workers.dev/sse')
)

In Other MCP Clients

The server follows the MCP specification and can be used with any MCP-compatible client:

Local installation:

npx nimiq-mcp

Remote access:

Tools Endpoint: https://nimiq-mcp.je-cf9.workers.dev/tools
Info Endpoint: https://nimiq-mcp.je-cf9.workers.dev/info
Health Check: https://nimiq-mcp.je-cf9.workers.dev/health
Web Interface: https://nimiq-mcp.je-cf9.workers.dev/

Development

Local Development

# Install dependencies
pnpm install

# Run linting
pnpm run lint

# Fix linting issues
pnpm run lint:fix

# Build for production
pnpm run build

# Test the server manually
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

Cloudflare Workers Development

# Install dependencies including Wrangler
pnpm install

# Start local development server
pnpm run dev:worker

# Build and test worker deployment
pnpm run build:worker

# Deploy to Cloudflare
pnpm run deploy

Deployment to Cloudflare Workers

See the complete Deployment Guide for detailed instructions.

Quick deployment steps:

Set up Cloudflare account and get API token
Configure GitHub secrets (for automatic deployment):
- CLOUDFLARE_API_TOKEN
- CLOUDFLARE_ACCOUNT_ID
Push to main branch - automatic deployment via GitHub Actions

Configure production secrets (optional):

wrangler secret put NIMIQ_RPC_URL
wrangler secret put NIMIQ_RPC_USERNAME
wrangler secret put NIMIQ_RPC_PASSWORD

The worker will be available at: https://nimiq-mcp.je-cf9.workers.dev

Architecture

The MCP server is built using:

@modelcontextprotocol/sdk: Official MCP SDK for TypeScript
nimiq-rpc-client-ts: Fully typed Nimiq RPC client
rpc.nimiqwatch.com: Free public Nimiq RPC service
Valibot: Runtime schema validation and type safety for all tool inputs
Cloudflare Workers: Edge compute platform for remote deployment
TypeScript: For type safety and better development experience

MCP 2025-06-18 Protocol Features

This server implements the latest Model Context Protocol specification (2025-06-18) with enhanced features:

Elicitation Support: Interactive tools can request additional information from users during execution
Enhanced Input Validation: Comprehensive schema validation with detailed error messages
Structured Tool Responses: JSON Schema definitions for better LLM comprehension
Improved Error Handling: Standardized error responses with proper MCP error codes
Protocol Version Compliance: Full support for the latest MCP specification requirements

Deployment Options

Local Deployment (STDIO Transport)

Runs as a local process communicating via stdin/stdout
Best for desktop applications and local development
Zero network configuration required
Inherently secure (no network exposure)

Remote Deployment (SSE Transport)

Deployed on Cloudflare Workers edge network
Accessible from anywhere via HTTPS
Supports multiple concurrent clients
Built-in security, rate limiting, and global CDN
Automatic scaling and high availability

Input Validation

The server uses Valibot for comprehensive input validation on all tools, providing:

Runtime Type Safety: All tool inputs are validated against strict schemas
Descriptive Error Messages: Clear validation errors with field-level details
Type Inference: Automatic TypeScript type inference from Valibot schemas
Default Values: Automatic application of default values for optional parameters
Enum Validation: Strict validation of allowed values for parameters like network types

Example validation:

const StakingRewardsSchema = v.object({
  amount: v.optional(v.pipe(v.number(), v.description('Initial amount staked in NIM')), 1),
  days: v.optional(v.pipe(v.number(), v.description('Number of days staked')), 365),
  network: v.optional(v.pipe(v.picklist(['main-albatross', 'test-albatross']), v.description('Network name')), 'main-albatross'),
})

Error Handling

The server includes comprehensive error handling:

RPC connection errors
Rate limit handling
Invalid parameters
Network timeouts
Graceful shutdown on SIGINT

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests and linting
Submit a pull request

License

MIT License - see LICENSE file for details.