Content
<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" />
</br>
Nimiq MCP Server</h1>
<p align="center">
A Model Context Protocol (MCP) server for interacting with the <b>Nimiq blockchain</b>.
</p>
<br/>
<p align="center">
<a href="https://www.npmjs.com/package/nimiq-mcp">
<img src="https://img.shields.io/npm/v/nimiq-mcp.svg" alt="npm version" />
</a>
<a href="https://www.npmjs.com/package/nimiq-mcp">
<img src="https://img.shields.io/npm/dm/nimiq-mcp.svg" alt="npm downloads" />
</a>
<a href="https://github.com/onmax/nimiq-mcp/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/onmax/nimiq-mcp.svg" alt="License" />
</a>
<a href="https://modelcontextprotocol.io">
<img src="https://img.shields.io/badge/MCP-Compatible-blue.svg" alt="MCP Compatible" />
</a>
<a href="https://nimiq.dev">
<img src="https://img.shields.io/badge/Nimiq-Blockchain-orange.svg" alt="Nimiq Blockchain" />
</a>
<p align="center">
<a href="https://modelcontextprotocol.io">
📖 Model Context Protocol
</a>
</p>
</p>
## 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:
```json
{
"mcpServers": {
"nimiq": {
"url": "https://nimiq-mcp.je-cf9.workers.dev/sse",
"transport": "sse"
}
}
}
```
### Option 2: Local Installation
Add this to your MCP client configuration:
```json
{
"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>
```json
{
"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>
```json
{
"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
```json
{
"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
```json
{
"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
```json
{
"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`:
```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`:
```json
{
"mcpServers": {
"nimiq": {
"command": "npx",
"args": ["nimiq-mcp"]
}
}
}
```
### With Custom Local Configuration
```json
{
"mcpServers": {
"nimiq": {
"command": "npx",
"args": [
"nimiq-mcp",
"--rpc-url",
"https://rpc.nimiqwatch.com"
]
}
}
}
```
### In Web Applications
Access the remote server directly via HTTP:
```javascript
// 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:**
```bash
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
```bash
# 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
```bash
# 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](DEPLOYMENT.md) for detailed instructions.
**Quick deployment steps:**
1. **Set up Cloudflare account and get API token**
2. **Configure GitHub secrets** (for automatic deployment):
- `CLOUDFLARE_API_TOKEN`
- `CLOUDFLARE_ACCOUNT_ID`
3. **Push to main branch** - automatic deployment via GitHub Actions
4. **Configure production secrets** (optional):
```bash
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](https://github.com/modelcontextprotocol/typescript-sdk)**: Official MCP SDK for TypeScript
- **[nimiq-rpc-client-ts](https://github.com/onmax/albatross-rpc-client-ts/)**: Fully typed Nimiq RPC client
- **[rpc.nimiqwatch.com](https://rpc.nimiqwatch.com/)**: Free public Nimiq RPC service
- **[Valibot](https://valibot.dev/)**: Runtime schema validation and type safety for all tool inputs
- **[Cloudflare Workers](https://workers.cloudflare.com/)**: 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:
```typescript
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
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
