ts-hedera-mcp

A TypeScript Model Context Protocol (MCP) server that exposes Hedera blockchain functionality as tools for AI assistants and applications.

Overview

This MCP server provides access to essential Hedera blockchain operations through a clean, standardized interface. It enables AI assistants to interact with the Hedera network for account management, consensus messaging, and HBAR transfers.

Features

Hedera Operations

• Account Management: Create new accounts and retrieve account information
• Consensus Service: Create topics and send messages to topics
• Cryptocurrency: Transfer HBAR between accounts
• Network Support: Works with Hedera testnet, mainnet, and previewnet

Technical Features

• Clean Architecture: Minimal file structure with clear separation of concerns
• Type Safety: Full TypeScript implementation with Zod schema validation
• Schema Validation: Runtime validation of all tool arguments using Zod
• Error Handling: Comprehensive error handling with descriptive validation messages
• Docker Support: Containerized deployment ready
• Environment Configuration: Flexible configuration via environment variables

Project Structure

ts-hedera-mcp/
├── src/
│   ├── index.ts                 # Main server entry point
│   ├── config/
│   │   └── hedera-config.ts     # Hedera network configuration
│   ├── schemas/
│   │   └── hedera-schemas.ts    # Zod validation schemas
│   ├── services/
│   │   └── hedera-service.ts    # Core Hedera blockchain operations
│   └── tools/
│       └── hedera-tools.ts      # MCP tool definitions
├── Dockerfile                   # Container configuration
├── docker-compose.yml           # Docker Compose deployment
├── env.example                  # Environment variables example
├── package.json                 # Project dependencies and scripts
├── tsconfig.json               # TypeScript configuration
└── README.md                   # This file

Available Tools

1. create_account

Creates a new Hedera account with an optional initial balance.

Parameters:

• initialBalance (optional): Initial balance in HBAR (default: 0)

Returns: Account ID, public key, private key, and transaction details

2. get_account_info

Retrieves detailed information about a Hedera account.

Parameters:

• accountId (required): Account ID in format 0.0.xxxxx

Returns: Account balance, key, staking info, and other account details

3. create_topic

Creates a new Hedera Consensus Service topic for messaging.

Parameters:

• memo (optional): Description for the topic (max 100 characters)

Returns: Topic ID and transaction details

4. send_topic_message

Sends a message to a Hedera Consensus Service topic.

Parameters:

• topicId (required): Topic ID in format 0.0.xxxxx
• message (required): Message content (max 1024 characters)

Returns: Message confirmation and transaction details

5. transfer_hbar

Transfers HBAR from one account to another.

Parameters:

• fromAccountId (required): Source account ID
• toAccountId (required): Destination account ID
• amount (required): Amount in HBAR
• fromPrivateKey (required): Private key of source account

Returns: Transfer confirmation and transaction details

Setup and Installation

Prerequisites

• Node.js 18+
• Hedera testnet account (get from Hedera Portal)
• Docker (for containerized deployment)

Local Development Setup

1. Clone the repository:

   git clone <repository-url>
   cd ts-hedera-mcp
   

2. Install dependencies:

   pnpm install
   

3. Configure environment:

   cp env.example .env
   

   Edit .env with your Hedera credentials:

   HEDERA_OPERATOR_ACCOUNT_ID=0.0.12345
   HEDERA_OPERATOR_PRIVATE_KEY=302e020100300506032b65700422042012345...
   HEDERA_NETWORK=testnet
   

4. Build the project:

   pnpm run build
   

5. Run the server:

   pnpm start
   

Docker Deployment

Option 1: Docker Compose (Recommended)

1. Configure environment:

   cp env.example .env
   

   Edit .env with your Hedera credentials.

2. Deploy with Docker Compose:

   docker-compose up -d
   

3. View logs:

   docker-compose logs -f ts-hedera-mcp
   

4. Stop the service:

   docker-compose down
   

Option 2: Manual Docker Build

1. Build the Docker image:

   docker build -t ts-hedera-mcp .
   

2. Run the container:

   docker run -e HEDERA_OPERATOR_ACCOUNT_ID=0.0.12345 \
              -e HEDERA_OPERATOR_PRIVATE_KEY=your_private_key \
              -e HEDERA_NETWORK=testnet \
              ts-hedera-mcp
   

Usage in MCP Clients

Claude Desktop

Add to your claude_desktop_config.json:

{
	"mcpServers": {
		"hedera": {
			"command": "node",
			"args": ["/path/to/ts-hedera-mcp/dist/index.js"],
			"env": {
				"HEDERA_OPERATOR_ACCOUNT_ID": "0.0.12345",
				"HEDERA_OPERATOR_PRIVATE_KEY": "your_private_key",
				"HEDERA_NETWORK": "testnet"
			}
		}
	}
}

Docker with MCP Client

Using Docker Compose

First, start the service with Docker Compose:

docker-compose up -d

Then configure your MCP client to connect via stdio:

{
	"mcpServers": {
		"hedera": {
			"command": "docker",
			"args": ["exec", "-i", "ts-hedera-mcp", "node", "dist/index.js"]
		}
	}
}

Using Direct Docker Run

{
	"mcpServers": {
		"hedera": {
			"command": "docker",
			"args": [
				"run",
				"--rm",
				"-i",
				"-e",
				"HEDERA_OPERATOR_ACCOUNT_ID=0.0.12345",
				"-e",
				"HEDERA_OPERATOR_PRIVATE_KEY=your_private_key",
				"-e",
				"HEDERA_NETWORK=testnet",
				"ts-hedera-mcp"
			]
		}
	}
}

Other MCP Clients

The server uses stdio transport and follows the MCP protocol standard, making it compatible with any MCP client implementation.

Configuration

Environment Variables

Variable	Required	Default	Description
HEDERA_OPERATOR_ACCOUNT_ID	Yes	-	Your Hedera account ID
HEDERA_OPERATOR_PRIVATE_KEY	Yes	-	Your Hedera account private key
HEDERA_NETWORK	No	testnet	Hedera network (testnet/mainnet/previewnet)

Getting Hedera Credentials

1. Visit Hedera Portal
2. Create a testnet account
3. Note your Account ID and Private Key
4. Use these in your environment configuration

Development

Scripts

• pnpm run build: Compile TypeScript to JavaScript
• pnpm run start: Run the compiled server
• pnpm run dev: Watch mode for development
• pnpm run clean: Remove compiled files

Architecture

The server follows clean architecture principles:

• Configuration Layer (config/): Handles environment setup and client configuration
• Schema Layer (schemas/): Zod validation schemas for type safety
• Service Layer (services/): Core business logic for Hedera operations
• Tools Layer (tools/): MCP tool definitions and schemas
• Transport Layer (index.ts): MCP server setup and request routing

Type Safety

The project uses Zod for runtime type validation:

• Schema Definitions: Each operation has a corresponding Zod schema (<Operation>ArgsSchema)
• Runtime Validation: All tool arguments are validated before processing
• Type Inference: TypeScript types are automatically inferred from Zod schemas
• Error Messages: Detailed validation error messages help with debugging
• JSON Schema Generation: Zod schemas are converted to JSON schemas for MCP tool definitions

Error Handling & Logging

All operations include comprehensive error handling and detailed logging:

• Environment validation on startup with detailed error messages
• Input validation for all tools with Zod schema validation
• Structured logging with prefixed categories ([SERVER], [TOOL], [HEDERA], [CONFIG])
• Transaction tracing with transaction IDs and step-by-step execution logs
• Error context including error types, messages, and relevant parameters
• Proper error propagation to MCP clients with user-friendly messages

Logging Categories

• [SERVER] - MCP server lifecycle and request handling
• [TOOL] - Tool execution, validation, and results
• [HEDERA] - Blockchain operations and transaction details
• [CONFIG] - Environment setup and client configuration

Security Considerations

• Private keys are handled securely and never logged
• Docker container runs as non-root user
• Input validation prevents injection attacks
• Environment variables used for sensitive configuration

Troubleshooting

Common Issues

1. Missing Environment Variables

   • Ensure all required environment variables are set
   • Check that account ID format is correct (0.0.xxxxx)

2. Network Connection Issues

   • Verify network connectivity
   • Check Hedera network status
   • Ensure firewall allows outbound connections

3. Transaction Failures

   • Verify account has sufficient balance
   • Check private key format and permissions
   • Ensure account exists on the specified network

Debug Mode

The application includes comprehensive logging by default. All logs are output to stderr using console.error() and include structured prefixes for easy filtering:

# View all logs
docker-compose logs -f ts-hedera-mcp

# Filter by category (if using grep)
docker-compose logs -f ts-hedera-mcp | grep "\[HEDERA\]"  # Blockchain operations
docker-compose logs -f ts-hedera-mcp | grep "\[TOOL\]"    # Tool execution
docker-compose logs -f ts-hedera-mcp | grep "\[SERVER\]"  # Server lifecycle
docker-compose logs -f ts-hedera-mcp | grep "\[CONFIG\]"  # Configuration

Set NODE_ENV=development for any additional framework-level debugging.

Examples

Creating an Account

{
	"tool": "create_account",
	"arguments": {
		"initialBalance": 10
	}
}

Getting Account Information

{
	"tool": "get_account_info",
	"arguments": {
		"accountId": "0.0.12345"
	}
}

Transferring HBAR

{
	"tool": "transfer_hbar",
	"arguments": {
		"fromAccountId": "0.0.12345",
		"toAccountId": "0.0.67890",
		"amount": 5,
		"fromPrivateKey": "your_private_key"
	}
}

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Create an issue in the repository
• Check Hedera documentation at docs.hedera.com
• Visit Hedera Discord community