Permaweb MCP 🧠⚡️

A streamlined MCP server for AO process management, Arweave deployment, and ArNS domain operations

Permaweb MCP is a Model Context Protocol (MCP) server that provides core infrastructure for interacting with the AO ecosystem and Arweave network. Built with TypeScript and FastMCP, it delivers 16 essential tools across 4 categories: Process management, Arweave deployment, wallet operations, and ArNS domain management.

🚀 Quick Start

NPM Package Installation

# Install globally for CLI usage
npm install -g permaweb-mcp

# Or install locally in your project
npm install permaweb-mcp

# Start the MCP server
npx permaweb-mcp

MCP Server Setup

For Claude Desktop

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

{
  "mcpServers": {
    "permaweb-mcp": {
      "command": "npx",
      "args": ["permaweb-mcp"],
      "env": {
        "SEED_PHRASE": "your twelve word mnemonic phrase here for deterministic wallet"
      }
    }
  }
}

For VS Code with Claude Code Extension

1. Install Claude Code Extension: Search for “Claude Code” in VS Code marketplace
2. Configure MCP Server: Add to your VS Code settings or workspace configuration:

{
  "mcpServers": {
    "permaweb-mcp": {
      "command": "npx",
      "args": ["permaweb-mcp"],
      "env": {
        "SEED_PHRASE": "your twelve word mnemonic phrase here"
      }
    }
  }
}

Environment Configuration

Create a .env file or set environment variables:

# Required: Deterministic wallet generation
SEED_PHRASE="your twelve word mnemonic phrase here"

# Optional: Development mode
NODE_ENV=development

---

🌟 Why Permaweb MCP?

🚀 Key Features

🔧 Process Management (4 Tools)

• spawnProcess: Create new AO processes with custom configurations
• sendAOMessage: Send messages with custom tags and data to processes
• readAOProcess: Read process state via dryrun queries (read-only)
• queryAOProcessMessages: Query and filter process message history

📦 Arweave Deployment (4 Tools)

• deployPermawebDirectory: Deploy entire directories to Permaweb
• checkPermawebDeployPrerequisites: Verify deployment requirements
• uploadToArweave: Upload single files to Arweave
• uploadFolderToArweave: Upload folders with automatic file handling

💰 Wallet Operations (2 Tools)

• generateKeypair: Generate Arweave keypair from seed phrase
• getUserPublicKey: Get user’s public key (wallet address)

🌐 ArNS Management (6 Tools)

• buyArnsRecord: Purchase ArNS names (lease or permanent)
• getArnsRecordInfo: Fetch ArNS record details and configurations
• getArnsTokenCost: Query current ArNS pricing
• resolveArnsName: Resolve ArNS name to transaction ID
• transferArnsRecord: Transfer ArNS record ownership
• updateArnsRecord: Update ArNS record properties

🎯 Developer Experience

• MCP Native: Works with Claude Desktop, VS Code, Cursor, and more
• TypeScript Built: Full type safety and modern development experience
• Zero Config: Automatic wallet generation from mnemonic phrase

---

📋 Core Architecture

Components:

• MCP Server: FastMCP-based server exposing 16 tools across 4 categories
• AO Integration: Direct communication with AO processes via @permaweb/aoconnect
• Arweave Deployment: File and directory uploads via Turbo SDK
• ArNS Management: Comprehensive domain operations via AR.IO SDK
• Service Layer: 12 specialized services supporting tool operations

---

💡 Usage Examples

Process Management

# Create a new AO process
"Spawn a new AO process with the default module and scheduler"

# Deploy Lua code to a process
"Send a message to process xyz123 with Action: Eval and this Lua code: Handlers.add('ping', ...)"

# Read process state
"Read the state of process xyz123 using a dryrun query"

# Query process messages
"Show me the last 50 messages for process xyz123"

Arweave Deployment

# Upload a single file
"Upload my-file.json to Arweave"

# Deploy a directory to Permaweb
"Deploy the ./dist directory to Permaweb with index.html as the entry point"

# Check deployment prerequisites
"Check if I have the necessary prerequisites to deploy to Permaweb"

ArNS Domain Management

# Get domain information
"Get the ArNS record for 'example'"

# Purchase an ArNS name
"Purchase the ArNS name 'myapp' as a permabuy"

# Manage domain settings
"Increase the undername limit for 'myapp' by 10"

---

🔧 Configuration Options

Environment Variables

# Core Configuration
SEED_PHRASE="your twelve word mnemonic phrase"     # Required for wallet
NODE_ENV="production"                              # production | development

# AO Integration
AO_SCHEDULER="https://ao-scheduler-url"           # Custom AO scheduler
AO_MODULE="custom-module-id"                      # Custom AO module

# Logging and Debug
DEBUG=true                                         # Enable debug mode
MCP_LOG_LEVEL=info                                # Logging level

Advanced MCP Configuration

{
  "mcpServers": {
    "permaweb-mcp": {
      "command": "npx",
      "args": ["permaweb-mcp"],
      "env": {
        "SEED_PHRASE": "your twelve word mnemonic phrase",
        "NODE_ENV": "production"
      }
    }
  }
}

---

🌐 Ecosystem & Links

Core Technologies

• AO Cookbook - AO development guide and compute layer
• Arweave - Permanent data storage
• Model Context Protocol - AI tool standard
• FastMCP - TypeScript MCP framework
• AR.IO SDK - ArNS and gateway operations

Protocol Standards

• AO Specification - AO compute layer specification
• Arweave Name System (ArNS) - Decentralized naming system
• Model Context Protocol - AI tool integration standard

Community & Support

• NPM Package: https://www.npmjs.com/package/permaweb-mcp
• Discord Community: Join Discord
• Twitter Updates: @allidoizcode

Related Projects

• AO Cookbook - AO development guide
• Arweave Cookbook - Arweave development
• Claude Desktop - Primary MCP client
• VS Code Claude Extension - Claude in VS Code

---

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/ALLiDoizCode/Permaweb-MCP.git
cd Permaweb-MCP

# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm run dev

# Build for production
npm run build

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• AO & Arweave Teams - For building the permanent compute and storage layers
• Anthropic - For creating the Model Context Protocol and Claude
• FastMCP Contributors - For the excellent TypeScript MCP framework
• Community Contributors - For feedback, testing, and contributions

---