sei-protocol · codebycarson · Sep 5, 2025 · Sep 8, 2025 · Sep 8, 2025 · Sep 8, 2025
diff --git a/.changeset/cold-sites-hear.md b/.changeset/cold-sites-hear.md
@@ -0,0 +1,5 @@
+---
+"@sei-js/mcp-server": minor
+---
+
+Add local docker tools to create and start local sei chains
diff --git a/docs/mcp-server/environment-variables.mdx b/docs/mcp-server/environment-variables.mdx
@@ -125,6 +125,21 @@ The Sei MCP Server supports configuration through environment variables, which c
 - **Description**: Base path for HTTP endpoints
 - **Format**: Must start with `/` (automatically normalized)
 
+### Docker Configuration
+
+#### `SEI_DOCKER_ENABLED`
+- **Type**: `string`
+- **Default**: `"false"`
+- **Description**: Enable Docker tools for local Sei blockchain development
+- **Options**: 
+  - `"false"` - Docker tools disabled (default)
+  - `"true"` - Enable Docker container management tools
+- **Prerequisites**: Docker must be installed and running on your system
+
+<Info>
+**Docker Tools**: When enabled, provides 6 additional tools for managing local Sei blockchain containers including start, stop, restart, and cleanup operations.
+</Info>
+
 ### System Configuration
 
 #### `PATH`
@@ -248,6 +263,48 @@ The Sei MCP Server supports configuration through environment variables, which c
 
     **Status**: Deprecated - migrate to streamable-http for better performance
   </Accordion>
+
+  <Accordion title="Local Development with Docker">
+    Enable Docker tools for local blockchain development:
+
+    <Tabs>
+      <Tab title="JSON Config">
+        ```json
+        {
+          "mcpServers": {
+            "sei": {
+              "command": "npx",
+              "args": ["-y", "@sei-js/mcp-server"],
+              "env": {
+                "SEI_DOCKER_ENABLED": "true",
+                "WALLET_MODE": "private-key",
+                "PRIVATE_KEY": "0x123..."
+              }
+            }
+          }
+        }
+        ```
+      </Tab>
+      <Tab title="CLI">
+        ```bash
+        # Enable Docker tools with wallet support
+        SEI_DOCKER_ENABLED=true \
+        WALLET_MODE=private-key \
+        PRIVATE_KEY=0x123... \
+        npx @sei-js/mcp-server
+
+        # Or with Claude CLI
+        claude mcp add sei-docker npx @sei-js/mcp-server \
+          --env SEI_DOCKER_ENABLED=true \
+          --env WALLET_MODE=private-key \
+          --env PRIVATE_KEY=0x123...
+        ```
+      </Tab>
+    </Tabs>
+
+    **Use Case**: Local development, testing, and blockchain experimentation
+    **Tools Added**: get_sei_releases, start_sei_chain, get_running_chains, restart_sei_container, stop_sei_chain, delete_sei_container
+  </Accordion>
 </AccordionGroup>
 
 ## Security Best Practices
@@ -286,6 +343,12 @@ The Sei MCP Server supports configuration through environment variables, which c
 - Verify JSON syntax in MCP configuration
 - Check for typos in variable names
 
+**Docker Tools Not Available**
+- Ensure Docker is installed and running: `docker --version`
+- Verify `SEI_DOCKER_ENABLED=true` is set correctly
+- Check Docker daemon is accessible: `docker ps`
+- Restart MCP server after enabling Docker tools
+
 <Card title="Need More Help?" icon="bug" href="/mcp-server/troubleshooting">
   Check our comprehensive troubleshooting guide for solutions to specific problems.
 </Card>
diff --git a/docs/mcp-server/introduction.mdx b/docs/mcp-server/introduction.mdx
@@ -97,8 +97,9 @@ icon: "robot"
             "SERVER_PATH": "/mcp",
             "MAINNET_RPC_URL": "https://evm-rpc.sei-apis.com",
             "TESTNET_RPC_URL": "https://evm-rpc-testnet.sei-apis.com",
-            "DEVNET_RPC_URL": "https://evm-rpc-arctic-1.sei-apis.com"
-          }
+            "DEVNET_RPC_URL": "https://evm-rpc-arctic-1.sei-apis.com",
+						"SEI_DOCKER_ENABLED": "true",
+						}
         }
       }
     }
@@ -113,6 +114,7 @@ icon: "robot"
 The Model Context Protocol is an open standard that connects AI systems with custom prompts, tools and data sources (context). It enables things like:
 
 - **Real-time blockchain data access** - Get current balances, transaction history, and network status directly from Sei
+- **Local development environment** - Spin up complete Sei blockchain containers for testing and development
 - **Full execution and write operations** - Deploy contracts, execute transactions, and interact with smart contracts (with wallet configured)
 - **Up-to-date documentation access** - Search both main Sei docs and Sei-JS package documentation for comprehensive guidance
 - **Specialized blockchain capabilities** - Access Sei-specific features like precompiles and native token operations
@@ -136,7 +138,7 @@ The Sei MCP Server leverages this protocol to bring all of this and more directl
   </Accordion>
 
   <Accordion title="Comprehensive Toolkit" icon="toolbox">
-    Access 29 blockchain tools covering token management, NFT operations, smart contract interactions, network monitoring, and documentation search.
+    Access 35+ blockchain tools covering token management, NFT operations, smart contract interactions, network monitoring, local development with Docker, and documentation search.
   </Accordion>
 </AccordionGroup>
 
@@ -148,6 +150,9 @@ The Sei MCP Server leverages this protocol to bring all of this and more directl
 "Generate a boilerplate dApp with Sei Global Wallet connection"
 "What's my SEI balance?"
 "Send 1 SEI to this address"
+"Start a local Sei blockchain for testing"
+"Show me all running Sei containers"
+"Stop my local blockchain and clean up"
 ```
 
 ## Next Steps

diff --git a/docs/mcp-server/quickstart.mdx b/docs/mcp-server/quickstart.mdx
@@ -126,6 +126,9 @@ icon: "download"
 
         # Wallet-enabled mode
         claude mcp add sei-mcp-server-wallet npx @sei-js/mcp-server --env WALLET_MODE=private-key PRIVATE_KEY=0x123...
+
+        # Docker-enabled mode for local development
+        claude mcp add sei-mcp-server-docker npx @sei-js/mcp-server --env SEI_DOCKER_ENABLED=true WALLET_MODE=private-key PRIVATE_KEY=0x123...
         ```
       </Step>
 
@@ -233,6 +236,16 @@ After setup, verify the server is working by asking your AI assistant:
 
     This confirms wallet tools are enabled.
   </Step>
+
+  <Step title="Test Docker Tools (Optional)">
+    If you enabled Docker tools with `SEI_DOCKER_ENABLED=true`:
+
+    **Ask:** "What Sei chain versions are available?"
+
+    **Ask:** "Start a local Sei blockchain"
+
+    This confirms Docker tools are working.
+  </Step>
 </Steps>
 
 ## Next Steps
@@ -242,7 +255,7 @@ After setup, verify the server is working by asking your AI assistant:
     Configure wallet access and custom RPC endpoints
   </Card>
   <Card title="Available Tools" icon="wrench" href="/mcp-server/tools">
-    Explore 50+ blockchain tools and capabilities
+    Explore 35+ blockchain tools and capabilities
   </Card>
   <Card title="Troubleshooting" icon="bug" href="/mcp-server/troubleshooting">
     Solutions to common setup and configuration issues

diff --git a/docs/mcp-server/tools.mdx b/docs/mcp-server/tools.mdx
@@ -4,7 +4,7 @@ description: "Complete reference of all Sei MCP server tools"
 icon: "wrench"
 ---
 
-The Sei MCP Server provides various tools for blockchain operations, queries, documentation lookup, and more. **By default, wallet tools are disabled** and only read-only tools are available. [Enable wallet tools](/mcp-server/quickstart#wallet-connection) to unlock transaction capabilities.
+The Sei MCP Server provides various tools for blockchain operations, queries, documentation lookup, local development, and more. **By default, wallet tools are disabled** and only read-only tools are available. [Enable wallet tools](/mcp-server/quickstart#wallet-connection) to unlock transaction capabilities.
 
 <Note>
 **Wallet Tools Disabled by Default**
@@ -116,6 +116,49 @@ These tools require [wallet configuration](/mcp-server/quickstart#wallet-connect
 | `search_docs` | Search the main Sei docs for general chain information, ecosystem providers, and user onboarding guides | "How do I bridge tokens to Sei?" |
 | `search_sei_js_docs` | Search Sei-JS documentation | "How do I use precompiles with Viem?" |
 
+## Local Development (Docker Tools) 🐳
+
+<Info>
+**Docker Required**: These tools require Docker to be installed and running on your system. Enable with `SEI_DOCKER_ENABLED=true`.
+</Info>
+
+Manage local Sei blockchain containers for development and testing:
+
+| Tool | Purpose | Example Usage |
+|------|---------|---------------|
+| `get_sei_releases` | Get available Sei chain releases | "What Sei versions are available?" |
+| `start_sei_chain` | Start local Sei blockchain container | "Start a local Sei chain with version v6.1.0" |
+| `get_running_chains` | List running Sei containers | "Show me all running Sei containers" |
+| `restart_sei_container` | Restart stopped Sei container | "Restart my sei-chain-latest container" |
+| `stop_sei_chain` | Stop running Sei container | "Stop my local blockchain" |
+| `delete_sei_container` | Delete Sei container | "Delete the sei-chain-v6.1.0 container" |
+
+### Docker Tool Features
+
+- **Multi-version support**: Run different Sei chain versions simultaneously
+- **Pre-configured accounts**: Test accounts with funds automatically created
+- **Port management**: Configurable RPC, REST, EVM, and gRPC ports
+- **Container lifecycle**: Full start, stop, restart, and cleanup operations
+- **GitHub integration**: Fetch latest releases directly from sei-protocol/sei-chain
+
+### Enabling Docker Tools
+
+To use Docker tools, add the environment variable to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "sei": {
+      "command": "npx",
+      "args": ["-y", "@sei-js/mcp-server"],
+      "env": {
+        "SEI_DOCKER_ENABLED": "true"
+      }
+    }
+  }
+}
+```
+
 ## Enabling Wallet Tools
 
 To use wallet-required tools (🔐), you must configure a wallet connection:

diff --git a/docs/mcp-server/troubleshooting.mdx b/docs/mcp-server/troubleshooting.mdx
@@ -147,7 +147,92 @@ Many issues stem from incorrect environment variable configuration.
   </Step>
 </Steps>
 
+### Docker Issues
 
+Problems with Docker tools and local blockchain containers.
+
+<Steps>
+  <Step title="Docker Not Available">
+    If Docker tools aren't showing up or you get "Docker not available" errors:
+
+    ```bash
+    # Check if Docker is installed
+    docker --version
+
+    # Check if Docker daemon is running
+    docker ps
+
+    # Verify SEI_DOCKER_ENABLED is set
+    echo $SEI_DOCKER_ENABLED
+    ```
+
+    **Solutions:**
+    - Install Docker from [docker.com](https://docker.com)
+    - Start Docker Desktop or Docker daemon
+    - Ensure `SEI_DOCKER_ENABLED=true` in your MCP configuration
+    - Restart your AI assistant after enabling Docker tools
+  </Step>
+
+  <Step title="Container Start Failures">
+    If Sei containers fail to start or crash immediately:
+
+    ```bash
+    # Check Docker logs
+    docker logs sei-chain-latest
+
+    # Check available system resources
+    docker system df
+
+    # Check port conflicts
+    lsof -i :26657 -i :1317 -i :8545 -i :9090
+    ```
+
+    **Common causes:**
+    - Port conflicts (26657, 1317, 8545, 9090 already in use)
+    - Insufficient disk space or memory
+    - Docker image corruption
+
+    **Solutions:**
+    - Stop conflicting services or use different ports
+    - Free up disk space (`docker system prune`)
+    - Pull fresh Docker image (`docker pull ghcr.io/sei-protocol/sei:latest`)
+  </Step>
+
+  <Step title="Image Pull Failures">
+    If Docker images fail to download:
+
+    ```bash
+    # Test Docker Hub connectivity
+    docker pull hello-world
+
+    # Try pulling Sei image manually
+    docker pull ghcr.io/sei-protocol/sei:latest
+    ```
+
+    **Solutions:**
+    - Check internet connection
+    - Verify Docker Hub/GitHub Container Registry access
+    - Try different network (corporate firewalls may block)
+    - Use VPN if in restricted region
+  </Step>
+
+  <Step title="Container Management Issues">
+    If containers won't stop, restart, or delete:
+
+    ```bash
+    # Force stop container
+    docker stop sei-chain-latest --time 0
+
+    # Force remove container
+    docker rm sei-chain-latest --force
+
+    # Clean up all stopped containers
+    docker container prune
+    ```
+
+    **Use with caution:** Force operations may cause data loss.
+  </Step>
+</Steps>
 
 ## Error Reference
 
@@ -168,6 +253,18 @@ Many issues stem from incorrect environment variable configuration.
     **Cause**: Invalid RPC URL or network connectivity issues
     **Solution**: Check your RPC URLs and internet connection
   </Card>
+  <Card title="'Docker not available'" icon="docker">
+    **Cause**: Docker not installed, not running, or SEI_DOCKER_ENABLED not set
+    **Solution**: Install Docker, start daemon, and set SEI_DOCKER_ENABLED=true
+  </Card>
+  <Card title="'Port already in use'" icon="network-port">
+    **Cause**: Required ports (26657, 1317, 8545, 9090) are occupied by other services
+    **Solution**: Stop conflicting services or configure different ports
+  </Card>
+  <Card title="'Container failed to start'" icon="container">
+    **Cause**: Docker image issues, resource constraints, or configuration problems
+    **Solution**: Check Docker logs, free up resources, or pull fresh image
+  </Card>
 </CardGroup>
 
 ## Getting Help
@@ -188,6 +285,7 @@ If you're still experiencing problems, please [create an issue on GitHub](https:
     Include:
     - Operating system and version
     - Node.js version (`node --version`)
+    - Docker version (`docker --version`) if using Docker tools
     - MCP client (Cursor, Claude Desktop, etc.)
     - Your PATH (`echo $PATH`)
   </Step>

diff --git a/package.json b/package.json
@@ -13,7 +13,9 @@
 	},
 	"dependencies": {
 		"@biomejs/biome": "^1.9.4",
-		"@changesets/cli": "^2.28.1"
+		"@changesets/cli": "^2.28.1",
+		"optional": "^0.1.4",
+		"sharp": "^0.34.3"
 	},
 	"devDependencies": {
 		"@types/jest": "^29.5.14",

diff --git a/packages/mcp-server/.env.example b/packages/mcp-server/.env.example
@@ -17,6 +17,11 @@ SERVER_PORT=8080
 SERVER_HOST=localhost
 SERVER_PATH=/mcp
 
+# Docker Configuration
+# Enable Docker tools for local Sei chain development
+# Set to 'true' to enable Docker container management tools
+SEI_DOCKER_ENABLED=false
+
 # RPC URLs
 # Optional, only needed if you want to use a custom RPC URL
 MAINNET_RPC_URL=your_mainnet_rpc_url_here

diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json
@@ -24,6 +24,7 @@
 	"devDependencies": {
 		"@jest/globals": "^30.0.3",
 		"@types/cors": "^2.8.17",
+		"@types/dockerode": "^3.3.31",
 		"@types/express": "^5.0.0",
 		"typescript": "^5.8.3"
 	},
@@ -32,6 +33,7 @@
 		"@noble/hashes": "^1.8.0",
 		"commander": "^14.0.0",
 		"cors": "^2.8.5",
+		"dockerode": "^4.0.2",
 		"dotenv": "^16.5.0",
 		"express": "^4.21.2",
 		"jest": "^30.0.3",