Keeperhub MCP

🚀 KeeperHub MCP Server

The Model Context Protocol (MCP) server for KeeperHub enables AI agents to create, manage, and execute blockchain automation workflows.

✨ Features

• Full CRUD operations: Perform create, read, update, and delete operations on workflows.
• AI-powered workflow generation: Generate workflows via natural language prompts.
• Async execution: Execute workflows asynchronously with status polling and log retrieval.
• MCP Resources: Expose workflow definitions.
• API Key authentication: Ensure secure access.

📦 Installation

Using Docker (Recommended)

# Build the Docker image
docker build -t keeperhub-mcp .

# Run the server
docker run -i --rm \
  -e KEEPERHUB_API_KEY=your_api_key_here \
  keeperhub-mcp

Using Node.js

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run the server
KEEPERHUB_API_KEY=your_api_key_here pnpm start

Development Mode

# Run with tsx for hot reloading
KEEPERHUB_API_KEY=your_api_key_here pnpm dev

📚 Documentation

Configuration

The server requires the following environment variables:

Transport Modes

The server supports two transport modes:

1. Stdio Mode (default): For local AI clients using stdin/stdout communication.
2. HTTP/SSE Mode: For remote AI agents using Server - Sent Events over HTTP.

To enable HTTP mode, set the PORT environment variable. When running in HTTP mode, you must also set MCP_API_KEY for authentication.

MCP Client Configuration

Stdio Mode (Local)

Add this to your MCP client configuration (e.g., Claude Code config):

{
  "mcpServers": {
    "keeperhub": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "KEEPERHUB_API_KEY",
        "keeperhub-mcp"
      ]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "keeperhub": {
      "command": "node",
      "args": [
        "/absolute/path/to/keeperhub-mcp/dist/index.js"
      ],
      "env": {
        "KEEPERHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

HTTP/SSE Mode (Remote)

For remote AI agents, run the server in HTTP mode:

# Using Node.js
PORT=3000 \
MCP_API_KEY=your_secure_mcp_key \
KEEPERHUB_API_KEY=your_keeperhub_key \
pnpm start

Or using Docker:

docker run -p 3000:3000 \
  -e PORT=3000 \
  -e MCP_API_KEY=your_secure_mcp_key \
  -e KEEPERHUB_API_KEY=your_keeperhub_key \
  keeperhub-mcp

The server will expose the following endpoints:

• GET /health - Health check endpoint
• GET /sse - Server - Sent Events endpoint for MCP protocol
• POST /message - Message endpoint for client requests

Authentication

All HTTP requests must include an Authorization header with a Bearer token:

Authorization: Bearer your_secure_mcp_key

Example: Test Health Check

curl -H "Authorization: Bearer your_secure_mcp_key" \
  http://localhost:3000/health

💻 Usage Examples

Workflow Management

list_workflows

List workflows in the organization. Parameters:

• limit (optional): Maximum number of workflows to return.
• offset (optional): Number of workflows to skip.
• project_id (optional): Filter by project ID (use list_projects to discover IDs).
• tag_id (optional): Filter by tag ID (use list_tags to discover IDs). Example:

{
  "limit": 10,
  "offset": 0,
  "project_id": "proj_abc123",
  "tag_id": "tag_xyz789"
}

get_workflow

Get workflow details by ID. Parameters:

• workflow_id (required): The ID of the workflow to retrieve. Example:

{
  "workflow_id": "wf_abc123"
}

create_workflow

Create a new workflow. Parameters:

• name (required): Name of the workflow.
• description (optional): Optional description.
• project_id (optional): Project ID to assign (use list_projects to discover IDs).
• tag_id (optional): Tag ID to assign (use list_tags to discover IDs).
• nodes (optional): Workflow nodes array.
• edges (optional): Workflow edges array. Example:

{
  "name": "My Workflow",
  "description": "A simple workflow",
  "project_id": "proj_abc123",
  "tag_id": "tag_xyz789",
  "nodes": [
    {
      "id": "1",
      "type": "trigger",
      "data": { "type": "manual" }
    }
  ],
  "edges": []
}

update_workflow

Update workflow nodes/edges. Parameters:

• workflow_id (required): The ID of the workflow to update.
• name (optional): New name for the workflow.
• description (optional): New description.
• project_id (optional): Project ID to assign (null to unassign).
• tag_id (optional): Tag ID to assign (null to unassign).
• nodes (optional): Updated workflow nodes.
• edges (optional): Updated workflow edges. Example:

{
  "workflow_id": "wf_abc123",
  "name": "Updated Workflow Name",
  "project_id": "proj_abc123",
  "nodes": [...]
}

delete_workflow

Delete a workflow. Parameters:

• workflow_id (required): The ID of the workflow to delete. Example:

{
  "workflow_id": "wf_abc123"
}

AI Generation

ai_generate_workflow

AI - powered workflow generation from natural language. Parameters:

• prompt (required): Natural language description of the workflow.
• existing_workflow_id (optional): ID of an existing workflow to modify. Example:

{
  "prompt": "Create a workflow that monitors Ethereum wallet balance and sends a Discord notification when it changes"
}

Execution

execute_workflow

Start async execution of a workflow. Parameters:

• workflow_id (required): The ID of the workflow to execute.
• input (optional): Input data for the workflow. Example:

{
  "workflow_id": "wf_abc123",
  "input": {
    "walletAddress": "0x1234..."
  }
}

get_execution_status

Poll execution status. Parameters:

• execution_id (required): The ID of the execution to check. Example:

{
  "execution_id": "exec_xyz789"
}

get_execution_logs

Get execution logs. Parameters:

• execution_id (required): The ID of the execution to get logs for. Example:

{
  "execution_id": "exec_xyz789"
}

Organization

list_projects

List all projects in the organization. Parameters: none Example:

{}

list_tags

List all tags in the organization. Parameters: none Example:

{}

Direct On - Chain Execution

execute_transfer

Send ETH or ERC - 20 tokens directly without creating a workflow. Parameters:

• network (required): Blockchain network (e.g., "ethereum", "polygon", "base").
• recipient_address (required): Destination wallet address.
• amount (required): Amount in human - readable units (e.g., "0.1").
• token_address (optional): ERC - 20 contract address; omit for native transfers. Example:

{
  "network": "sepolia",
  "recipient_address": "0xRecipient...",
  "amount": "0.01"
}

execute_contract_call

Call any smart contract function directly. Auto - detects read vs write. Parameters:

• contract_address (required): Target contract address.
• network (required): Blockchain network.
• function_name (required): Function to call.
• function_args (optional): Arguments as JSON array string.
• abi (optional): ABI JSON string; auto - fetched if omitted.

execute_check_and_execute

Read a contract value, evaluate a condition, and execute a write if met. Parameters:

• contract_address (required): Contract to read.
• network (required): Blockchain network.
• function_name (required): Read function for condition.
• condition (required): {operator, value} — operators: eq, neq, gt, lt, gte, lte.
• action (required): {contract_address, function_name, ...} write to execute if condition is met.

get_direct_execution_status

Check status of a direct execution. Returns tx hash and block explorer link. Parameters:

• execution_id (required): ID returned from a direct execution call.

Available Resources

keeperhub://workflows

Returns a list of all workflows in the organization. URI: keeperhub://workflows MIME Type: application/json

keeperhub://workflows/{id}

Returns details for a specific workflow. URI: keeperhub://workflows/{workflow_id} MIME Type: application/json

API Key Management

To use this MCP server, you need to generate an API key from the KeeperHub application:

1. Log in to app.keeperhub.com.
2. Navigate to Organization Settings.
3. Go to the API Keys section.
4. Click "Create API Key".
5. Give it a name and copy the key (it will only be shown once).
6. Use the key in the KEEPERHUB_API_KEY environment variable.

🔧 Technical Details

Project Structure

keeperhub-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── http-server.ts        # HTTP/SSE transport server
│   ├── tools/
│   │   ├── index.ts          # Tool exports
│   │   ├── workflows.ts      # Workflow CRUD tools
│   │   ├── executions.ts     # Execution tools
│   │   └── generate.ts       # AI generation tool
│   ├── resources/
│   │   ├── index.ts          # Resource exports
│   │   └── workflows.ts      # Workflow resources
│   ├── client/
│   │   └── keeperhub.ts      # KeeperHub API client
│   └── types/
│       └── index.ts          # Type definitions
├── Dockerfile
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md

Building

pnpm build

Type Checking

pnpm type-check

Building Docker Image

docker build -t keeperhub-mcp .

Error Handling

All tools return errors in the following format:

{
  "content": [
    {
      "type": "text",
      "text": "Error: <error message>"
    }
  ],
  "isError": true
}

Common errors:

• 401 Unauthorized: Invalid or missing API key.
• 404 Not Found: Workflow or execution not found.
• 400 Bad Request: Invalid parameters.
• 500 Internal Server Error: Server error.

Security

• API keys are transmitted via Bearer authentication.
• Keys are scoped to a single organization.
• All communication with KeeperHub API is over HTTPS.
• Keys are never logged or exposed in error messages.

📄 License

MIT

Support

For issues or questions:

• GitHub Issues: techops-services/keeperhub-mcp
• Documentation: KeeperHub Docs