Crynux MCP Server

MCP server for Crynux Network operations, designed for LLM clients (such as Cursor, VS Code, and Claude Desktop) to perform most Crynux Network/Crynux Portal actions through standardized MCP tools.

Features

Wallet

• Wallet management with system keychain (create keys, sign messages/transactions, list/delete/export keys, set default key)

Blockchain

• Native CNX balance query on Crynux L2 networks
• Latest block height query on Crynux L2 networks
• Native CNX transfer
• Arbitrary transaction signing and raw transaction broadcast
• Beneficial address query and on-chain update
• Node staking query
• Node stake on the NodeStaking contract only (does not join Relay or start a node)
• Node tryUnstake and forceUnstake
• Delegated staking query, create/update, and unstake

Relay

• Relay account balance query
• Relay withdraw create/list/latest-status query
• Relay deposit initiate/list/latest-status query
• Staging and production Relay environments with env/network pairing

Tools

For the full action list and detailed input/output fields, see docs/tools.md.

Security notes

• The server never intentionally logs raw private keys.
• transfer_native, staking writes, sign_message, and sign_transaction read signer keys from your local system keychain.
• sign_message and sign_transaction never return the private key. sign_transaction returns only the signed raw_transaction and metadata.
• Optional fallback: if no keychain entry exists, it reads CRYNUX_PRIVATE_KEY from MCP server environment.
• The model only sees transfer fields (network, to, amount, and optional gas fields), not raw key material.
• Use dedicated low-risk wallets for AI operations, not treasury wallets.

Get Started

Step 1) Prerequisites

• Install Python 3.11 or newer.
• Open a terminal.

Step 2) Install the package

Install from PyPI (recommended):

python -m pip install crynux-mcp

If you are developing this repository, install from source in editable mode:

python -m pip install -e ".[dev]"

Step 3) Choose your AI client and add MCP config

You only need one client config (Cursor, VS Code, or Claude Desktop).

Cursor

Create or edit .cursor/mcp.json in your project:

{
  "mcpServers": {
    "crynux-mcp": {
      "command": "python",
      "args": ["-m", "crynux_mcp"]
    }
  }
}

VS Code

Create or edit .vscode/mcp.json in your project (or your user mcp.json):

{
  "servers": {
    "crynuxMcp": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "crynux_mcp"]
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "crynux-mcp": {
      "command": "python",
      "args": ["-m", "crynux_mcp"]
    }
  }
}

Step 4) Manage signer keys (cross-platform)

Run these commands in your terminal:

crynux-mcp key add --name main
crynux-mcp key create --name trading-bot
crynux-mcp key list
crynux-mcp key set-default --name main
crynux-mcp key delete --name trading-bot

key add prompts for your private key with hidden input and stores it in your OS keychain. key create generates a new private key and stores it directly in your OS keychain.

• Windows: Credential Manager
• macOS: Keychain
• Linux: Secret Service compatible keyring

Optional advanced fallback (if you do not want keychain): set CRYNUX_PRIVATE_KEY in MCP server env.

Step 5) Restart your AI client

After saving MCP config, fully restart the client so it reloads servers.

Step 6) Verify the server is loaded

In your AI client, check MCP tool list and confirm wallet, blockchain, and Relay actions are available. Use docs/tools.md as the source of truth for the full action catalog.

Step 7) First tool calls

Example: query balance

• network: crynux-on-base
• address: your EVM address
• unit: ether

Example: send native CNX

• network: crynux-on-base
• key_name: main (optional, uses default local key if omitted)
• to: recipient EVM address
• amount: for example 0.1
• unit: ether

Example: query Relay account balance

• relay_env: production (or staging)
• address: your wallet EVM address
• key_name: main (optional)

Relay auth token is obtained and refreshed internally for authenticated Relay actions.

Example: create Relay withdraw request

• network: crynux-on-base
• relay_env: production
• address: your wallet EVM address
• amount_wei: for example 1000000000000000000 (1 CNX)
• key_name: main (optional)

Example: initiate Relay deposit (on-chain transfer)

• network: crynux-on-base
• relay_env: production
• amount: for example 1
• unit: ether
• key_name: main (optional)

relay_env=staging MUST be paired with crynux-on-base-sepolia. relay_env=production MUST be paired with crynux-on-base.

Signer key source for transfer:

• Named key in system keychain set by crynux-mcp key add or crynux-mcp key create (preferred)
• CRYNUX_PRIVATE_KEY env var fallback

Step 8) Optional local manual run

You can start the MCP server process directly for debugging:

python -m crynux_mcp

Spec and transport

• MCP protocol target: 2025-11-25
• Runtime transport: stdio (local process, no HTTP server required)

Release

Maintainer release instructions are in RELEASE.md.

Network configuration

Chain metadata is stored in:

• src/crynux_mcp/config/chains.json

Update this file to change RPC URLs, chain IDs, or contract addresses.

Relay API configuration is stored in:

• src/crynux_mcp/config/relay.json

Update this file to change Relay environments, URLs, timeout, and per-environment deposit addresses.

Tests

pytest