{"id":29408931,"url":"https://github.com/onmax/nimiq-mcp","last_synced_at":"2026-01-17T17:13:27.271Z","repository":{"id":298154055,"uuid":"999051380","full_name":"onmax/nimiq-mcp","owner":"onmax","description":" A Model Context Protocol (MCP) server for interacting with the Nimiq blockchain. ","archived":false,"fork":false,"pushed_at":"2025-11-05T15:12:55.000Z","size":478,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-05T16:22:02.922Z","etag":null,"topics":["mcp","nimiq"],"latest_commit_sha":null,"homepage":"https://nimiq-mcp.je-cf9.workers.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onmax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-09T16:59:55.000Z","updated_at":"2025-10-28T19:02:48.000Z","dependencies_parsed_at":"2025-10-06T20:23:31.401Z","dependency_job_id":"694f5725-9852-481e-8357-1effd047be87","html_url":"https://github.com/onmax/nimiq-mcp","commit_stats":null,"previous_names":["onmax/nimiq-mcp"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/onmax/nimiq-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnimiq-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnimiq-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnimiq-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnimiq-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onmax","download_url":"https://codeload.github.com/onmax/nimiq-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnimiq-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28512086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","nimiq"],"created_at":"2025-07-11T04:00:49.325Z","updated_at":"2026-01-17T17:13:27.237Z","avatar_url":"https://github.com/onmax.png","language":"TypeScript","funding_links":[],"categories":["Developer Resources"],"sub_categories":["Developer Tool"],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg 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\" /\u003e\n  \u003c/br\u003e\n  Nimiq MCP Server\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\nA Model Context Protocol (MCP) server for interacting with the \u003cb\u003eNimiq blockchain\u003c/b\u003e.\n\u003c/p\u003e\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/nimiq-mcp\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/nimiq-mcp.svg\" alt=\"npm version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/nimiq-mcp\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dm/nimiq-mcp.svg\" alt=\"npm downloads\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/onmax/nimiq-mcp/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/onmax/nimiq-mcp.svg\" alt=\"License\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/MCP-Compatible-blue.svg\" alt=\"MCP Compatible\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://nimiq.dev\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Nimiq-Blockchain-orange.svg\" alt=\"Nimiq Blockchain\" /\u003e\n  \u003c/a\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://modelcontextprotocol.io\"\u003e\n      📖 Model Context Protocol\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n## Features\n\n- 🚀 **Two deployment options**: Zero-setup remote access OR local installation\n- 🔗 **Nimiq blockchain tools** for accounts, transactions, blocks, and validators\n- ⚡ **Remote option**: No installation required - just add the URL to your MCP client\n- 🔧 **Local option**: Full control with `npx nimiq-mcp`\n- 🔒 **Read-only operations** (sending transactions not supported for security)\n\n## Quick Start\n\nChoose one of two options:\n\n### Option 1: Remote Access\n\nAdd this to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"nimiq\": {\n      \"url\": \"https://nimiq-mcp.je-cf9.workers.dev/sse\",\n      \"transport\": \"sse\"\n    }\n  }\n}\n```\n\n### Option 2: Local Installation\n\nAdd this to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"nimiq\": {\n      \"command\": \"npx\",\n      \"args\": [\"nimiq-mcp\"]\n    }\n  }\n}\n```\n\n## Comparison\n\n| Feature              | Remote Access                   | Local Installation           |\n| -------------------- | ------------------------------- | ---------------------------- |\n| **Setup**            | Zero installation required      | Requires Node.js/npm         |\n| **Updates**          | Automatic                       | Manual (npx pulls latest)    |\n| **Privacy**          | Requests go through our servers | Direct connection to RPC     |\n| **Availability**     | Depends on our service uptime   | Depends on local environment |\n| **Protocol Support** | SSE transport only              | Full MCP protocol support    |\n\n### With Custom RPC Endpoint \u0026 Auth\n\n\u003cdetails\u003e\n\u003csummary\u003eRemote (SSE)\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"nimiq\": {\n      \"url\": \"https://nimiq-mcp.je-cf9.workers.dev/sse?rpc-url=https://your-rpc-endpoint.com\u0026rpc-username=your-username\u0026rpc-password=your-password\",\n      \"transport\": \"sse\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLocal (npx)\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"nimiq\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"nimiq-mcp\",\n        \"--rpc-url\",\n        \"https://your-rpc-endpoint.com\",\n        \"--rpc-username\",\n        \"your-username\",\n        \"--rpc-password\",\n        \"your-password\"\n      ]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n## Available Arguments\n\n| CLI Arguments               | URL Arguments             | Description                     | Default                      |\n| --------------------------- | ------------------------- | ------------------------------- | ---------------------------- |\n| `--rpc-url \u003curl\u003e`           | `rpc-url=\u003curl\u003e`           | Nimiq RPC endpoint URL          | `https://rpc.nimiqwatch.com` |\n| `--rpc-username \u003cusername\u003e` | `rpc-username=\u003cusername\u003e` | RPC username for authentication | None                         |\n| `--rpc-password \u003cpassword\u003e` | `rpc-password=\u003cpassword\u003e` | RPC password for authentication | None                         |\n| `--help, -h`                | N/A                       | Show help message               | N/A                          |\n\n## Available Tools and Resources\n\nThe MCP server provides comprehensive tools and resources for interacting with the Nimiq blockchain:\n\n### Tools (17 available)\n\n| Category                         | Tool                       | Description                                                    |\n| -------------------------------- | -------------------------- | -------------------------------------------------------------- |\n| **Blockchain Data Tools**        | `getHead`                  | Get the current head block of the Nimiq blockchain             |\n|                                  | `getBlockByNumber`         | Retrieve a specific block by its number                        |\n|                                  | `getBlockByHash`           | Retrieve a specific block by its hash                          |\n|                                  | `getEpochNumber`           | Get the current epoch number                                   |\n| **Blockchain Calculation Tools** | `getSupply`                | Get the current circulating supply of NIM                      |\n|                                  | `calculateSupplyAt`        | Calculate the Nimiq PoS supply at a given time                 |\n|                                  | `calculateStakingRewards`  | Calculates the potential wealth accumulation based on staking  |\n|                                  | `getPrice`                 | Get the price of NIM against other currencies                  |\n| **Account \u0026 Balance Tools**      | `getAccount`               | Get detailed account information by address                    |\n|                                  | `getBalance`               | Get the balance of a specific account address                  |\n| **Transaction Tools**            | `getTransaction`           | Get detailed transaction information by hash                   |\n|                                  | `getTransactionsByAddress` | Get transaction history for a specific address                 |\n| **Validator Tools**              | `getValidators`            | Get information about all active validators                    |\n|                                  | `getValidator`             | Get detailed information about a specific validator            |\n|                                  | `getSlots`                 | Get validator slot information for current or specific block   |\n| **Network Tools**                | `getNetworkInfo`           | Get network status including peer count and consensus state    |\n| **Documentation Tools**          | `getRpcMethods`            | Get all available RPC methods from the latest OpenRPC document |\n|                                  | `searchDocs`               | Search through the Nimiq documentation using full-text search  |\n\n### Resources (3 available)\n\n| Category                    | Resource                  | Description                                                 |\n| --------------------------- | ------------------------- | ----------------------------------------------------------- |\n| **Documentation Resources** | `nimiq://docs/web-client` | Complete web-client documentation for LLMs                  |\n|                             | `nimiq://docs/protocol`   | Complete Nimiq protocol and learning documentation for LLMs |\n|                             | `nimiq://docs/validators` | Complete validator and staking documentation for LLMs       |\n\n### Tool Parameters\n\nEach tool accepts specific parameters:\n\n- **Block tools**: `includeBody` (boolean) to include transaction details\n- **Address tools**: `address` (string) for Nimiq addresses\n- **Transaction tools**: `hash` (string) for transaction hashes, `max` (number) for limits\n- **Documentation tools**: `includeSchemas` (boolean) for `getRpcMethods` to include detailed parameter/result schemas\n- **Search tools**: `query` (string) for search terms, `limit` (number) to control result count\n\n### Resource Access\n\nResources are accessed via their URI and don't require parameters:\n\n- **Documentation resources**: Access via `nimiq://docs/web-client`, `nimiq://docs/protocol`, or `nimiq://docs/validators`\n- Content is returned as plain text for optimal LLM consumption\n- MCP clients can cache resource content for improved performance\n\n### Example Responses\n\n#### Supply Data Response\n\n```json\n{\n  \"total\": 210000000000000,\n  \"vested\": 0,\n  \"burned\": 0,\n  \"max\": 210000000000000,\n  \"initial\": 25200000000000,\n  \"staking\": 100000000000,\n  \"minted\": 1000000000,\n  \"circulating\": 25200000000000,\n  \"mined\": 0,\n  \"updatedAt\": \"2025-01-20T12:00:00.000Z\"\n}\n```\n\n#### Block Data Response\n\n```json\n{\n  \"blockNumber\": 21076071,\n  \"block\": {\n    \"hash\": \"90e2ba0a831eec477bca1a26ba8c5e2b3162b5d042667828c4db0f735247d41e\",\n    \"number\": 21076071,\n    \"timestamp\": 1749486768481,\n    \"parentHash\": \"b4fae3fc846ac13bfc62aa502c8683e25e92616d987f3f642b9cb57da73b6392\",\n    \"type\": \"micro\",\n    \"producer\": {\n      \"slotNumber\": 305,\n      \"validator\": \"NQ51 LM8E Q8LS 53TX GGDG 26M4 VX4Y XRE2 8JDT\"\n    }\n  },\n  \"timestamp\": \"2025-06-09T16:32:49.055Z\",\n  \"network\": \"mainnet\"\n}\n```\n\n#### Search Documentation Response\n\n```json\n{\n  \"query\": \"validator staking\",\n  \"totalResults\": 3,\n  \"results\": [\n    {\n      \"title\": \"Validator Setup\",\n      \"content\": \"To become a validator in Nimiq, you need to stake NIM tokens...\",\n      \"section\": \"Validators\",\n      \"score\": 0.95,\n      \"snippet\": \"...validator in Nimiq, you need to stake NIM tokens and run validator software...\"\n    },\n    {\n      \"title\": \"Staking Rewards\",\n      \"content\": \"Validators earn rewards for producing blocks and validating transactions...\",\n      \"section\": \"Economics\",\n      \"score\": 0.87,\n      \"snippet\": \"...earn rewards for producing blocks and validating transactions. Staking rewards...\"\n    }\n  ],\n  \"searchedAt\": \"2025-01-20T12:00:00.000Z\"\n}\n```\n\n## Usage Examples\n\n### Claude Desktop Configuration\n\n**Option 1: Remote (Zero Setup)**\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"nimiq\": {\n      \"url\": \"https://nimiq-mcp.je-cf9.workers.dev/sse\",\n      \"transport\": \"sse\"\n    }\n  }\n}\n```\n\n**Option 2: Local Installation**\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"nimiq\": {\n      \"command\": \"npx\",\n      \"args\": [\"nimiq-mcp\"]\n    }\n  }\n}\n```\n\n### With Custom Local Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"nimiq\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"nimiq-mcp\",\n        \"--rpc-url\",\n        \"https://rpc.nimiqwatch.com\"\n      ]\n    }\n  }\n}\n```\n\n### In Web Applications\n\nAccess the remote server directly via HTTP:\n\n```javascript\n// Connect to the remote MCP server\nconst mcpClient = new SSEClientTransport(\n  new URL('https://nimiq-mcp.je-cf9.workers.dev/sse')\n)\n```\n\n### In Other MCP Clients\n\nThe server follows the MCP specification and can be used with any MCP-compatible client:\n\n**Local installation:**\n\n```bash\nnpx nimiq-mcp\n```\n\n**Remote access:**\n\n- **Tools Endpoint**: `https://nimiq-mcp.je-cf9.workers.dev/tools`\n- **Info Endpoint**: `https://nimiq-mcp.je-cf9.workers.dev/info`\n- **Health Check**: `https://nimiq-mcp.je-cf9.workers.dev/health`\n- **Web Interface**: `https://nimiq-mcp.je-cf9.workers.dev/`\n\n## Development\n\n### Local Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Run linting\npnpm run lint\n\n# Fix linting issues\npnpm run lint:fix\n\n# Build for production\npnpm run build\n\n# Test the server manually\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | node dist/index.js\n```\n\n### Cloudflare Workers Development\n\n```bash\n# Install dependencies including Wrangler\npnpm install\n\n# Start local development server\npnpm run dev:worker\n\n# Build and test worker deployment\npnpm run build:worker\n\n# Deploy to Cloudflare\npnpm run deploy\n```\n\n### Deployment to Cloudflare Workers\n\nSee the complete [Deployment Guide](DEPLOYMENT.md) for detailed instructions.\n\n**Quick deployment steps:**\n\n1. **Set up Cloudflare account and get API token**\n2. **Configure GitHub secrets** (for automatic deployment):\n   - `CLOUDFLARE_API_TOKEN`\n   - `CLOUDFLARE_ACCOUNT_ID`\n3. **Push to main branch** - automatic deployment via GitHub Actions\n4. **Configure production secrets** (optional):\n   ```bash\n   wrangler secret put NIMIQ_RPC_URL\n   wrangler secret put NIMIQ_RPC_USERNAME\n   wrangler secret put NIMIQ_RPC_PASSWORD\n   ```\n\nThe worker will be available at: `https://nimiq-mcp.je-cf9.workers.dev`\n\n## Architecture\n\nThe MCP server is built using:\n\n- **[@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)**: Official MCP SDK for TypeScript\n- **[nimiq-rpc-client-ts](https://github.com/onmax/albatross-rpc-client-ts/)**: Fully typed Nimiq RPC client\n- **[rpc.nimiqwatch.com](https://rpc.nimiqwatch.com/)**: Free public Nimiq RPC service\n- **[Valibot](https://valibot.dev/)**: Runtime schema validation and type safety for all tool inputs\n- **[Cloudflare Workers](https://workers.cloudflare.com/)**: Edge compute platform for remote deployment\n- **TypeScript**: For type safety and better development experience\n\n### Deployment Options\n\n**Local Deployment (STDIO Transport)**\n\n- Runs as a local process communicating via stdin/stdout\n- Best for desktop applications and local development\n- Zero network configuration required\n- Inherently secure (no network exposure)\n\n**Remote Deployment (SSE Transport)**\n\n- Deployed on Cloudflare Workers edge network\n- Accessible from anywhere via HTTPS\n- Supports multiple concurrent clients\n- Built-in security, rate limiting, and global CDN\n- Automatic scaling and high availability\n\n### Input Validation\n\nThe server uses **Valibot** for comprehensive input validation on all tools, providing:\n\n- **Runtime Type Safety**: All tool inputs are validated against strict schemas\n- **Descriptive Error Messages**: Clear validation errors with field-level details\n- **Type Inference**: Automatic TypeScript type inference from Valibot schemas\n- **Default Values**: Automatic application of default values for optional parameters\n- **Enum Validation**: Strict validation of allowed values for parameters like network types\n\nExample validation:\n\n```typescript\nconst StakingRewardsSchema = v.object({\n  amount: v.optional(v.pipe(v.number(), v.description('Initial amount staked in NIM')), 1),\n  days: v.optional(v.pipe(v.number(), v.description('Number of days staked')), 365),\n  network: v.optional(v.pipe(v.picklist(['main-albatross', 'test-albatross']), v.description('Network name')), 'main-albatross'),\n})\n```\n\n## Error Handling\n\nThe server includes comprehensive error handling:\n\n- RPC connection errors\n- Rate limit handling\n- Invalid parameters\n- Network timeouts\n- Graceful shutdown on SIGINT\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and linting\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonmax%2Fnimiq-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonmax%2Fnimiq-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonmax%2Fnimiq-mcp/lists"}