NEAR Contract Deployer MCP Server

An MCP (Model Context Protocol) server that enables AI assistants like Claude to deploy, initialize, and upgrade NEAR smart contracts.

Features

• deploy_contract: Deploy WASM smart contracts to NEAR accounts
• initialize_contract: Call initialization methods after deployment
• upgrade_contract: Upgrade existing contracts with new code
• get_deployment_status: Check if an account has a contract deployed
• estimate_deployment_cost: Calculate storage costs before deploying

Installation

npm install
npm run build

Configuration

Credentials

The server looks for NEAR credentials in these locations (in order):

1. ~/.near-credentials/{network}/{account_id}.json
2. ~/.near/credentials/{network}/{account_id}.json
3. ./.near-credentials/{network}/{account_id}.json

You can also provide credentials directly via the private_key parameter.

Generate Credentials

# For testnet
near login --networkId testnet

# For mainnet  
near login --networkId mainnet

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "near-deploy": {
      "command": "node",
      "args": ["/path/to/mcp-near-deploy/dist/index.js"]
    }
  }
}

Example Conversations

Deploying a New Contract

User: Deploy my contract to testnet

Claude: I'll help you deploy your contract. First, let me estimate the costs.

Tool: estimate_deployment_cost
Args: {"wasm_path": "./target/wasm32-unknown-unknown/release/my_contract.wasm"}

💰 DEPLOYMENT COST ESTIMATE

📊 Cost Breakdown:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  WASM Size:       156.32 KB (160,072 bytes)
  Storage Cost:    1.600720 NEAR
  Estimated Gas:   11 TGas
  Total Estimate:  ~1.65 NEAR

💡 Recommendation:
   ✅ Contract size is reasonable. Deployment should proceed smoothly.

Now let me deploy it:

Tool: deploy_contract
Args: {
  "account_id": "mycontract.testnet",
  "wasm_path": "./target/wasm32-unknown-unknown/release/my_contract.wasm",
  "network": "testnet"
}

✅ CONTRACT DEPLOYED SUCCESSFULLY

📋 Deployment Details:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Contract ID:     mycontract.testnet
  Network:         testnet
  WASM Size:       156.32 KB
  Storage Cost:    1.600720 NEAR
  Transaction:     7abc123...

🔗 Explorer: https://explorer.testnet.near.org/transactions/7abc123...

📝 Next Steps:
  1. Initialize the contract using initialize_contract()
  2. Verify deployment with get_deployment_status()

---

Initializing a Contract

User: Initialize the contract with owner set to my account

Claude: I'll initialize your contract with the specified owner:

Tool: initialize_contract
Args: {
  "contract_id": "mycontract.testnet",
  "method_name": "new",
  "args": {"owner_id": "yourname.testnet"},
  "network": "testnet"
}

✅ CONTRACT INITIALIZED SUCCESSFULLY

📋 Initialization Details:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Contract ID:     mycontract.testnet
  Method:          new
  Arguments:       {"owner_id": "yourname.testnet"}
  Transaction:     8def456...

🔗 Explorer: https://explorer.testnet.near.org/transactions/8def456...

✨ The contract is now ready to use!

---

Checking Deployment Status

User: Is there a contract on wrap.near?

Claude: Let me check the deployment status:

Tool: get_deployment_status
Args: {"account_id": "wrap.near", "network": "mainnet"}

✅ CONTRACT IS DEPLOYED

📋 Deployment Status:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Contract ID:     wrap.near
  Network:         mainnet
  Code Hash:       4Fh7SHqU...
  Storage Used:    3,456,789 bytes
  Storage Cost:    34.567890 NEAR
  Balance:         1,234.567890 NEAR

🔗 Explorer: https://explorer.near.org/accounts/wrap.near

✨ Contract is ready to interact with!

---

Upgrading a Contract

User: Upgrade my contract with the new version

Claude: I'll upgrade your contract with the new WASM and run the migration:

Tool: upgrade_contract
Args: {
  "contract_id": "mycontract.testnet",
  "wasm_path": "./target/wasm32-unknown-unknown/release/my_contract_v2.wasm",
  "migrate_method": "migrate",
  "network": "testnet"
}

✅ CONTRACT UPGRADED SUCCESSFULLY

📋 Upgrade Details:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Contract ID:     mycontract.testnet
  Network:         testnet
  New WASM Size:   162.45 KB
  Storage Cost:    1.624500 NEAR
  Deploy TX:       9ghi789...
  Migration TX:    0jkl012...

🔗 Explorer: https://explorer.testnet.near.org/transactions/9ghi789...

✨ Migration completed successfully!

---

Cost Estimation

User: How much will it cost to deploy a 500KB contract?

Claude: Let me calculate the deployment cost:

Tool: estimate_deployment_cost
Args: {"wasm_size_bytes": 512000}

💰 DEPLOYMENT COST ESTIMATE

📊 Cost Breakdown:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  WASM Size:       500.00 KB (512,000 bytes)
  
  Storage Cost:    5.120000 NEAR
                   (5120000000000000000000000 yoctoNEAR)
  
  Estimated Gas:   15 TGas
  Gas Cost:        ~0.001500 NEAR
  
  ─────────────────────────────────
  Total Estimate:  5.121500 NEAR

💡 Recommendation:
   💸 Storage cost is significant. Ensure account has sufficient NEAR balance.

📝 Notes:
   • Storage costs are exact (1 byte = 0.00001 NEAR)
   • Gas costs may vary based on network conditions
   • Add ~10% buffer for safety

API Reference

deploy_contract

Deploy a WASM smart contract to a NEAR account.

Parameter	Type	Required	Description
account_id	string	✅	NEAR account to deploy to
wasm_path	string	❌*	Path to WASM file
wasm_base64	string	❌*	Base64-encoded WASM
network	string	❌	"mainnet" or "testnet" (default: testnet)
private_key	string	❌	Signing key (ed25519:xxx format)

*Either wasm_path or wasm_base64 required

initialize_contract

Call an initialization method on a deployed contract.

Parameter	Type	Required	Description
contract_id	string	✅	Contract account ID
method_name	string	✅	Init method name
args	object	❌	Method arguments
deposit	string	❌	NEAR to attach (e.g., "1.5")
gas	string	❌	Gas limit in TGas (default: 100)
network	string	❌	"mainnet" or "testnet"
private_key	string	❌	Signing key

upgrade_contract

Upgrade an existing contract with new WASM code.

Parameter	Type	Required	Description
contract_id	string	✅	Contract to upgrade
wasm_path	string	❌*	Path to new WASM file
wasm_base64	string	❌*	Base64-encoded new WASM
migrate_method	string	❌	Migration method to call
migrate_args	object	❌	Migration arguments
network	string	❌	"mainnet" or "testnet"
private_key	string	❌	Signing key

get_deployment_status

Check if an account has a contract deployed.

Parameter	Type	Required	Description
account_id	string	✅	Account to check
network	string	❌	"mainnet" or "testnet" (default: mainnet)

estimate_deployment_cost

Calculate storage costs for deployment.

Parameter	Type	Required	Description
wasm_path	string	❌*	Path to WASM file
wasm_base64	string	❌*	Base64-encoded WASM
wasm_size_bytes	number	❌*	Direct size in bytes

*At least one required

Networks

• Mainnet: Production network (mainnet)
• Testnet: Development network (testnet)

Default network is testnet for safety.

Security Notes

• Never share or commit private keys
• Use environment variables or credential files for keys
• Test on testnet before mainnet deployments
• Review contract code before deploying

License

MIT