Hedera MCP Server

🚀 Hedera MCP Server

This project provides a server integrated with a Langchain wrapper for interacting with the Hedera network. It allows users to perform Hedera operations via natural language commands, which are implemented by the Langchain setup.

🚀 Quick Start

The entire project consists of two services that need to be run.

Prerequisites

Before you begin, ensure you have installed the following:

• Node.js (recommended version 20 or higher)
• pnpm (npm install -g pnpm)
• Git

Steps

1. Clone the repository:

   git clone https://github.com/mateuszm-arianelabs/hedera-mcp-server.git
   cd hedera-mcp-server
   

2. Set environment variables in the packages:

   • You need to copy the .env.example file and create .env files in two locations based on it:
     • packages/langchain-proxy
     • packages/mcp-server

   Edit the .env files and fill in the required configuration values (e.g., Hedera keys, network details).

   API_URL=                  # langchain proxy endpoint URL
   PORT=                     # Port on which the MCP server runs
   MCP_AUTH_TOKEN=           # Array of accepted tokens separated by commas
   LANGCHAIN_PROXY_TOKEN=    # Token to access the Langchain proxy
   

3. Install dependencies:

   pnpm install
   

4. Start the Langchain proxy service:

   pnpm run dev:lc
   

   (or pnpm start to use the production mode if configured).

5. Run the mcp server:

   pnpm run dev:mcp
   

   (or pnpm start to use the production mode if configured).

✨ Features

Interact with Hedera

This is the core feature that allows the server to make calls through the running Langchain wrapper service. The wrapper then interprets these requests and performs corresponding operations on the Hedera network (e.g., creating tokens, transferring HBAR, interacting with smart contracts).

Configuration for Visual Studio Code

To establish a connection with the MCP server, the X-MCP-AUTH-TOKEN header is required.

Here is an example .vscode/settings.json configuration for Visual Studio Code:

{
    "mcp": {
        "inputs": [],
        "servers": {
            "hedera": {
                "type": "sse",
                "url": "http://localhost:3000/sse",
                "headers": { "X-MCP-AUTH-TOKEN": "your-mcp-auth-token"}
            }
        }
    }
}

⚠️ Important Note

Currently, passing custom headers (e.g., X-MCP-AUTH-TOKEN) is not supported in the Cursor IDE. Source

Potential Transition to OAuth

• Hedera Token Service: Explore Hedera's Token Service and integrate it with smart contracts to implement more complex decentralized applications.
• Solidus Protocol: Learn how to use Solidus on the Hedera network to implement secure and scalable payment solutions.

Overall Architecture Diagram

Here is a brief description of the system components:

1. MCP Server: Responsible for handling requests from clients and interacting with the Hedera network through the Langchain wrapper.
2. Langchain Wrapper: Acts as an intermediary, converting natural language instructions into operations understandable by the Hedera network.
3. Hedera Network: Performs actual operations and returns results.

📚 Documentation

API Documentation

Request Structure

All requests must include the following:

• Content-Type: application/json

Response Structure

The response will be in JSON format, as shown below:

{
    "code": 200,
    "message": "Operation successful"
}

Example Error Response

When a valid token is not provided, the following is returned:

{
    "error": {
        "code": 401,
        "message": "Unauthorized: Missing valid X-MCP-AUTH-TOKEN header"
    }
}

Example Endpoints

Get Status

curl --location 'http://localhost:3000/status' \
--header 'X-MCP-AUTH-TOKEN: your-token'

Response:

{
    "status": "ok",
    "timestamp": "2024-01-01T00:00:00.000Z"
}

Execute Operation

curl --location 'http://localhost:3000/execute' \
--header 'X-MCP-AUTH-TOKEN: your-token' \
--data-raw '{"operation": "Create Token"}'

Response:

{
    "result": {
        "tokenAddress": "0.0.123456789"
    }
}

Conclusion

By following the above steps and documentation, you can easily set up and use the Hedera MCP server to interact with the Hedera network.