MoveFlow Aptos MCP Server

MoveFlow Aptos MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with the MoveFlow protocol on Aptos blockchain. This server provides a standardized interface for AI tools to create, manage, and interact with cryptocurrency streaming payments.

Features

• Stream Management

  • Create payment streams (regular or one-time payments)
  • Withdraw funds from active streams
  • Close existing streams
  • Extend stream durations
  • Pause and resume streams
  • Query stream information

• Batch Operations

  • Create multiple streams at once
  • Withdraw from multiple streams simultaneously

• MCP Integration

  • Full Model Context Protocol (MCP) compatibility
  • Automatic tool discovery through MCP capability interface
  • Standardized input schema validation
  • Self-documenting API

• Security

  • Client-side signing support for secure transaction handling
  • Read-only mode for safe data queries
  • Direct signing mode for development and testing

Available MCP Tools

The MoveFlow Aptos MCP server provides the following tools:

Tool Name	Description	Function
create-stream	Create a new MoveFlow stream	Creates a new cryptocurrency stream to transfer funds over time
withdraw-stream	Withdraw funds from a stream	Withdraws available funds from an active stream
close-stream	Close a MoveFlow stream	Terminates a stream and returns remaining funds to sender
extend-stream	Extend a stream's duration	Increases the end time of an existing stream
get-stream-info	Get stream information	Retrieves details about a specific stream
batch-create-streams	Create multiple streams	Creates multiple streams in a single transaction
batch-withdraw-streams	Withdraw from multiple streams	Withdraws from multiple streams in a single transaction
pause-stream	Pause a stream	Temporarily stops a stream's payments
resume-stream	Resume a paused stream	Restarts a paused stream

Available Resources

The MoveFlow Aptos MCP server also provides access to blockchain resources:

Resource URI	Description
moveflow://streams/active	Lists all active streams for the current account
moveflow://streams/{streamId}	Retrieves detailed information about a specific stream

These resources can be accessed directly by AI assistants supporting the MCP protocol, providing contextual information without requiring explicit tool calls.

Installation and Setup

1. Clone the repository:

   git clone https://github.com/moveflow/moveflow-aptos-mcp-server.git
   cd moveflow_aptos_mcp_server
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Start the server:

   APTOS_NODE_URL="https://fullnode.mainnet.aptoslabs.com/v1" \
   APTOS_NETWORK="mainnet" \
   READ_ONLY_MODE="true" \
   node build/index.js
   

5. Verify the server is running: You should see the following output:

   Starting MoveFlow Aptos MCP Server...
   Initialized Stream with read-only mode
   MoveFlow Aptos MCP Server tools registered
   MoveFlow Aptos MCP Server started
   

Installation via NPM Package

You can also install and use the server as an NPM package:

npm install @moveflow/aptos-mcp-server

AI Assistant Integration

Claude Desktop Integration

Add this server to your Claude Desktop configuration:

1. Open the Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the following configuration (adjust the path according to your setup):

{
  "mcpServers": {
    "moveflow-aptos": {
      "command": "node",
      "args": ["/path/to/moveflow_aptos_mcp_server/build/index.js"],
      "env": {
        "APTOS_NODE_URL": "https://fullnode.mainnet.aptoslabs.com/v1",
        "APTOS_NETWORK": "mainnet",
        "READ_ONLY_MODE": "true" // Set to "true" for read-only mode, omit for transaction preparation mode
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Using with NPX

You can run this server directly using npx without installing it globally:

# Run with default settings
npx @moveflow/aptos-mcp-server

# Run with custom environment variables
npx @moveflow/aptos-mcp-server --env.APTOS_NETWORK=testnet --env.READ_ONLY_MODE=true

For Claude Desktop integration with NPX:

{
  "mcpServers": {
    "moveflow-aptos": {
      "command": "npx",
      "args": ["-y", "@moveflow/aptos-mcp-server"],
      "env": {
        "APTOS_NODE_URL": "https://fullnode.mainnet.aptoslabs.com/v1",
        "APTOS_NETWORK": "mainnet",
        "READ_ONLY_MODE": "true"
      }
    }
  }
}

Other AI Plugin Integration

If you're developing your own AI plugin and want to integrate this MCP server, you can:

1. Add this repository as a dependency to your project
2. Start the server process
3. Communicate with the server through the MCP protocol

Example (TypeScript):

import { spawn } from 'child_process';
import { Client } from '@modelcontextprotocol/sdk/client';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio';

// Start the MCP server
const serverProcess = spawn('node', ['path/to/build/index.js'], {
  env: {
    ...process.env,
    APTOS_NODE_URL: 'https://fullnode.mainnet.aptoslabs.com/v1',
    APTOS_NETWORK: 'mainnet',
    READ_ONLY_MODE: "true" // Enable read-only mode
  }
});

// Connect to the MCP server
const client = new Client({version: '1.0.0'}, {capabilities: {}});
const transport = new StdioClientTransport({childProcess: serverProcess});
await client.connect(transport);

// Now you can use the client object to call MCP methods

Cline Integration

Cline is an autonomous coding agent in VS Code that supports MCP tools. To integrate the MoveFlow Aptos MCP server with Cline:

1. Install the Cline Extension: Install Cline from the VS Code extension marketplace

2. Configure the MoveFlow Aptos MCP server: Cline automatically searches for MCP servers in the ~/Documents/Cline/MCP directory. You can:

   • Method 1: Create a server configuration file

     mkdir -p ~/Documents/Cline/MCP
     touch ~/Documents/Cline/MCP/moveflow-aptos.json
     

     Add the following content to moveflow-aptos.json:

     {
       "name": "moveflow-aptos",
       "command": "node",
       "args": ["/path/to/moveflow_aptos_mcp_server/build/index.js"],
       "env": {
         "APTOS_NODE_URL": "https://fullnode.mainnet.aptoslabs.com/v1",
         "APTOS_NETWORK": "mainnet"
       }
     }
     

   • Method 2: Use Cline's natural language configuration In Cline, type:

     Add a tool that connects to Aptos blockchain using MoveFlow protocol
     

     Then follow the prompts to complete the configuration

3. Set up private key (optional):

   • For read-only operations, no private key is needed
   • For transaction operations, use environment variables or a .env file to set the private key, do NOT include the private key directly in the configuration file

4. Using the server's features: In Cline, you can access MoveFlow features using natural language, for example:

   Create a new payment stream on Aptos to address 0x123... for 100 APT over 30 days
   

   Or:

   Show me all my active MoveFlow streams on Aptos mainnet
   

⚠️ Security Note: Cline has its own security mechanisms and will ask for your permission before executing any operations. Nevertheless, it's recommended to follow the private key security best practices outlined in this document.

Security Architecture

This server implements a security architecture that eliminates private key storage:

Client-Side Signing Model

The server has been designed to completely avoid storing private keys:

1. Read-Only Mode:

   • Default recommended mode of operation
   • Only allows querying blockchain data
   • Cannot execute any transactions
   • Enable with READ_ONLY_MODE="true"

2. Transaction Preparation Mode:

   • When READ_ONLY_MODE is omitted or set to "false"
   • Server prepares transactions but doesn't sign them
   • Transactions must be signed by client applications
   • Provides enhanced security by separating transaction preparation from signing

3. Direct Signing Mode (For Development):

   • When SIGNING_MODE is set to "direct" and APTOS_PRIVATE_KEY is provided
   • Server uses the provided private key to sign and submit transactions
   • Less secure but convenient for testing
   • Not recommended for production use

Secure Transaction Architecture

The server architecture separates responsibilities:

• Server: Validates inputs and prepares transaction objects
• Client: Manages private keys and signs transactions
• API/Connector: Handles communication between server and client

This design eliminates the need for private key handling in the server process, making it significantly more secure for production use.

Testing MCP Tools

The server includes a test script to verify all MCP tools are working correctly:

# Run the test script
npm run test-tools

This will execute a series of tests for each MCP tool to verify proper functionality. You can also configure the test script to use different networks or signing modes by editing the configuration in test-tools.js.

Configuration Reference

Environment Variables

Variable	Description	Required	Default
APTOS_NODE_URL	Aptos node URL	Yes	https://fullnode.mainnet.aptoslabs.com/v1
APTOS_NETWORK	Network type: "mainnet", "testnet", "devnet", "local"	Yes	"mainnet"
READ_ONLY_MODE	Set to "true" to enable read-only mode	No	"false"
SIGNING_MODE	Signing mode: "direct" or "client"	No	"client"
APTOS_PRIVATE_KEY	Private key for direct signing mode	No*	-
APTOS_FAUCET_URL	Test/Dev network faucet URL	No	-

*Required only when SIGNING_MODE is set to "direct" and READ_ONLY_MODE is "false".

Server Modes

• Read-Only Mode: When READ_ONLY_MODE is set to "true". Server can only query blockchain data.
• Transaction Modes: When READ_ONLY_MODE is set to "false", the server can operate in two modes:
  • Client-Side Signing Mode (Default): When SIGNING_MODE is set to "client" or omitted. Server prepares transactions but doesn't sign them. Transactions must be signed by client applications.
  • Direct Signing Mode: When SIGNING_MODE is set to "direct" and APTOS_PRIVATE_KEY is provided. Server uses the provided private key to sign and submit transactions directly. This mode is less secure but more convenient for testing and development.

Development

Project Structure

The server codebase is organized as follows:

moveflow_aptos_mcp_server/
├── src/                    # Source code
│   ├── tools.ts            # MCP tool implementations
│   ├── resources.ts        # MCP resource implementations
│   ├── adapters.ts         # Adapters for Aptos SDK
│   ├── aptos.ts            # Aptos blockchain interactions
│   ├── config.ts           # Configuration handling
│   ├── index.ts            # Main server entry point
│   ├── utils.ts            # Utility functions
│   └── services/           # Service implementations
│       ├── TransactionSigningService.ts
│       ├── ClientProvidedSigningService.ts
│       └── TransactionProxyService.ts
├── build/                  # Compiled JavaScript
├── bin/                    # CLI tools
│   └── cli.js              # CLI entry point
└── test-tools.js           # Tools testing script

Building From Source

To build the server from source:

# Install dependencies
npm install

# Build TypeScript
npm run build

# Optionally run tests
npm run test-tools

License

MIT License