# HashPilot
[](https://www.npmjs.com/package/hashpilot)
[](https://opensource.org/licenses/Apache-2.0)
[](https://nodejs.org/)
**AI-powered MCP server for Hedera blockchain development**
HashPilot is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that integrates with AI assistants like Claude Desktop, Cursor, Windsurf, and VS Code to provide a complete toolkit for Hedera blockchain development.
## Quick Start
### Install via npm
```bash
npm install -g hashpilot
```
### Or use with npx (no install required)
```bash
npx hashpilot
```
## Editor Configuration
HashPilot works with any MCP-compatible editor. Configure your editor to use HashPilot:
### Claude Desktop
**Config file location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
**Configuration:**
```json
{
"mcpServers": {
"hashpilot": {
"command": "npx",
"args": ["-y", "hashpilot"],
"env": {
"HEDERA_NETWORK": "testnet",
"HEDERA_OPERATOR_ID": "0.0.YOUR_ACCOUNT_ID",
"HEDERA_OPERATOR_KEY": "YOUR_PRIVATE_KEY_HEX",
"OPENAI_API_KEY": "sk-YOUR_OPENAI_KEY"
}
}
}
}
```
### Cursor
**Config file location:**
- macOS: `~/.cursor/mcp.json`
- Windows: `%USERPROFILE%\.cursor\mcp.json`
- Linux: `~/.cursor/mcp.json`
**Configuration:**
```json
{
"mcpServers": {
"hashpilot": {
"command": "npx",
"args": ["-y", "hashpilot"],
"env": {
"HEDERA_NETWORK": "testnet",
"HEDERA_OPERATOR_ID": "0.0.YOUR_ACCOUNT_ID",
"HEDERA_OPERATOR_KEY": "YOUR_PRIVATE_KEY_HEX",
"OPENAI_API_KEY": "sk-YOUR_OPENAI_KEY"
}
}
}
}
```
### Windsurf
**Config file location:**
- macOS: `~/.codeium/windsurf/mcp_config.json`
- Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
- Linux: `~/.codeium/windsurf/mcp_config.json`
**Configuration:**
```json
{
"mcpServers": {
"hashpilot": {
"command": "npx",
"args": ["-y", "hashpilot"],
"env": {
"HEDERA_NETWORK": "testnet",
"HEDERA_OPERATOR_ID": "0.0.YOUR_ACCOUNT_ID",
"HEDERA_OPERATOR_KEY": "YOUR_PRIVATE_KEY_HEX",
"OPENAI_API_KEY": "sk-YOUR_OPENAI_KEY"
}
}
}
}
```
### VS Code (with MCP extension)
Install the [MCP extension](https://marketplace.visualstudio.com/items?itemName=anthropics.mcp) and add to your `settings.json`:
```json
{
"mcp.servers": {
"hashpilot": {
"command": "npx",
"args": ["-y", "hashpilot"],
"env": {
"HEDERA_NETWORK": "testnet",
"HEDERA_OPERATOR_ID": "0.0.YOUR_ACCOUNT_ID",
"HEDERA_OPERATOR_KEY": "YOUR_PRIVATE_KEY_HEX",
"OPENAI_API_KEY": "sk-YOUR_OPENAI_KEY"
}
}
}
}
```
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `HEDERA_NETWORK` | Yes | Network to use: `testnet`, `mainnet`, or `previewnet` |
| `HEDERA_OPERATOR_ID` | Yes | Your Hedera account ID (e.g., `0.0.12345`) |
| `HEDERA_OPERATOR_KEY` | Yes | Your private key in hex format |
| `OPENAI_API_KEY` | For RAG | Required for documentation search and code generation |
## Features
HashPilot provides 30+ MCP tools covering the complete Hedera development workflow:
### Account Management
- Create new accounts with ECDSA keys
- Query balances (HBAR and tokens)
- Transfer HBAR between accounts
- Get detailed account information
### Token Operations (HTS)
- Create fungible and non-fungible tokens
- Mint, burn, and transfer tokens
- Freeze/unfreeze accounts
- Manage KYC compliance
- Configure custom fees
### Consensus Service (HCS)
- Create and manage topics
- Submit messages (auto-chunking for large messages)
- Query message history
- Real-time subscriptions
### Smart Contracts
- Deploy contracts via Hardhat or Foundry
- Verify contracts on HashScan
- Call read-only functions (free)
- Execute state-changing transactions
- Full deployment history tracking
### JSON-RPC (EVM Compatibility)
- 55+ JSON-RPC methods supported
- `eth_call`, `eth_sendRawTransaction`, `eth_getLogs`
- Contract deployment and interaction
- Full EVM tooling compatibility
### Stablecoin Studio
- Create compliant stablecoins
- Role-based access control
- KYC/AML compliance features
- Proof-of-Reserve support
- Cash-in allowances
### Development Tools
- Hardhat integration (compile, test, deploy)
- Foundry integration (forge, cast, anvil)
- Error code explanations
- Address book management
- State backup/restore
## RAG-Powered Documentation
HashPilot includes a powerful RAG (Retrieval-Augmented Generation) system with **10,000+ pre-indexed documents** from the Hedera ecosystem:
### docs_search
Semantic search across all Hedera documentation:
```
"Search for token creation examples in JavaScript"
```
### docs_ask
Ask any question and get cited answers:
```
"How do I implement a multi-sig account on Hedera?"
```
### code_generate
Generate SDK code from natural language:
```
"Generate code to create an NFT collection with royalties"
```
**Indexed Sources:**
- Official Hedera Documentation
- SDK References (JavaScript, Java, Go, Rust, Python)
- Hedera Improvement Proposals (HIPs)
- Tutorials and Examples
- Smart Contract Patterns
**Note:** RAG features require an OpenAI API key for embeddings and completions.
## Requirements
- **Node.js** 18.0.0 or higher
- **Hedera Account** - Get a free testnet account at [portal.hedera.com](https://portal.hedera.com)
- **OpenAI API Key** - Required for RAG features (documentation search, code generation)
## Getting a Hedera Testnet Account
1. Visit [portal.hedera.com](https://portal.hedera.com)
2. Create a free account
3. Navigate to "Testnet" tab
4. Copy your Account ID and Private Key (DER encoded)
5. Convert DER to hex if needed, or use the raw hex key
## Example Usage
Once configured, ask your AI assistant:
> "Create a new Hedera account with 10 HBAR initial balance"
> "Deploy this Solidity contract to testnet using Hardhat"
> "Search the docs for HCS message chunking"
> "Generate code to create a fungible token with 2 decimals"
> "Explain the INSUFFICIENT_PAYER_BALANCE error"
## Links
- [HashPilot Documentation](https://hash-pilot.app/)
- [GitHub Repository](https://github.com/justmert/hashpilot)
- [npm Package](https://www.npmjs.com/package/hashpilot)
- [Hedera Documentation](https://docs.hedera.com)
- [MCP Protocol](https://modelcontextprotocol.io)
## License
Apache-2.0
## Contributing
Contributions are welcome! Please see our [GitHub repository](https://github.com/justmert/hashpilot) for guidelines.
