# 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](https://portal.hedera.com/))
- Docker (for containerized deployment)

### Local Development Setup

1. **Clone the repository:**

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

2. **Install dependencies:**

   ```bash
   pnpm install
   ```

3. **Configure environment:**

   ```bash
   cp env.example .env
   ```

   Edit `.env` with your Hedera credentials:

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

4. **Build the project:**

   ```bash
   pnpm run build
   ```

5. **Run the server:**
   ```bash
   pnpm start
   ```

### Docker Deployment

#### Option 1: Docker Compose (Recommended)

1. **Configure environment:**

   ```bash
   cp env.example .env
   ```

   Edit `.env` with your Hedera credentials.

2. **Deploy with Docker Compose:**

   ```bash
   docker-compose up -d
   ```

3. **View logs:**

   ```bash
   docker-compose logs -f ts-hedera-mcp
   ```

4. **Stop the service:**
   ```bash
   docker-compose down
   ```

#### Option 2: Manual Docker Build

1. **Build the Docker image:**

   ```bash
   docker build -t ts-hedera-mcp .
   ```

2. **Run the container:**
   ```bash
   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`:

```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:

```bash
docker-compose up -d
```

Then configure your MCP client to connect via stdio:

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

#### Using Direct Docker Run

```json
{
	"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](https://portal.hedera.com/)
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:

```bash
# 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

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

### Getting Account Information

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

### Transferring HBAR

```json
{
	"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](https://docs.hedera.com)
- Visit Hedera Discord community