THORChain MCP Server

# mcp-thorchain A Model Context Protocol (MCP) server providing access to THORChain blockchain data. This server enables AI assistants like Claude to query THORChain transactions, pools, network statistics, and vault addresses through a standardized interface. ## Features - **Transaction Lookup**: Get detailed information about specific THORChain transactions - **Address History**: Query transaction history for any blockchain address - **Pool Statistics**: Access liquidity pool data including prices, APY, and trading volume - **Pool Details**: Get in-depth information for specific liquidity pools - **Network Stats**: Retrieve network-wide statistics including swap volumes and active users - **Vault Addresses**: Get current inbound addresses for depositing funds to THORChain ## Requirements - Node.js >= 20.0.0 - npm or compatible package manager ## Installation ### From npm (Recommended) ```bash npm install -g @missionsquad/mcp-thorchain ``` ### From Source ```bash # Clone the repository git clone https://github.com/MissionSquad/mcp-thorchain.git cd mcp-thorchain # Install dependencies npm install # Build the project npm run build ``` ## Configuration ### Claude Desktop To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "thorchain": { "command": "node", "args": [ "/absolute/path/to/mcp-thorchain/dist/index.js" ] } } } ``` Replace `/absolute/path/to/mcp-thorchain` with the actual path to your installation directory. After adding the configuration: 1. Completely quit Claude Desktop (Cmd+Q on macOS, or via System Tray on Windows) 2. Reopen Claude Desktop 3. The THORChain tools should now be available ### Testing with MCP Inspector You can test the server without Claude Desktop using the MCP Inspector: ```bash npx @modelcontextprotocol/inspector node dist/index.js ``` This will open a web interface (usually at `http://localhost:5173`) where you can: - View all available tools - Test tool execution with custom parameters - See request/response data - Debug server behavior ## Available Tools ### 1. `get-transaction` Get detailed information about a specific THORChain transaction. **Parameters:** - `txid` (string, required): Transaction hash (64-character hexadecimal string) **Example:** ```typescript { "txid": "DC85CB537CB6082F61270D70C4058BB111475BCDC403E6E42AAF2106D067E1B4" } ``` ### 2. `get-address-history` Retrieve transaction history for a blockchain address. **Parameters:** - `address` (string, required): Blockchain address to query - `limit` (number, optional): Maximum transactions to return (default: 10, max: 50) - `offset` (number, optional): Pagination offset (default: 0) **Example:** ```typescript { "address": "thor1...", "limit": 20, "offset": 0 } ``` ### 3. `get-pools` Get statistics for all THORChain liquidity pools. **Parameters:** - `period` (enum, optional): Time period - "1h" | "24h" | "7d" | "30d" | "90d" | "365d" | "all" (default: "24h") **Example:** ```typescript { "period": "24h" } ``` ### 4. `get-pool-detail` Get detailed information for a specific liquidity pool. **Parameters:** - `asset` (string, required): Pool asset identifier (e.g., "BTC.BTC", "ETH.ETH") **Example:** ```typescript { "asset": "BTC.BTC" } ``` ### 5. `get-network-stats` Get overall THORChain network statistics. **Parameters:** None ### 6. `get-vault-addresses` Get current THORChain vault addresses for depositing funds. **Parameters:** None ## API Providers The server automatically rotates between multiple API providers for redundancy: **Primary**: Nine Realms (`https://midgard.ninerealms.com`, `https://thornode.ninerealms.com`) **Fallback**: Liquify (`https://midgard.thorchain.liquify.com`, `https://thornode.thorchain.liquify.com`) If the primary provider fails or times out, the server automatically tries the fallback provider. ## Development ### Build ```bash npm run build ``` ### Watch Mode ```bash npm run watch ``` ### Project Structure ``` mcp-thorchain/ ├── src/ │ ├── index.ts # MCP server and tool definitions │ ├── api-client.ts # THORChain API client with provider rotation │ └── types.ts # TypeScript type definitions ├── dist/ # Compiled JavaScript output ├── package.json ├── tsconfig.json └── README.md ``` ## Technical Details ### Dependencies - `@modelcontextprotocol/sdk@1.22.0`: MCP server SDK - `zod@3.23.8`: Schema validation ### Type Safety The project uses TypeScript with strict mode enabled. Due to a known incompatibility between Zod v3.23.8 (bundled with the MCP SDK) and TypeScript's type inference, the main server file uses `@ts-nocheck`. Runtime validation and type safety are maintained through Zod schemas. ### Error Handling - All API requests include 5-second timeouts - Automatic provider failover on connection errors - Comprehensive error messages with context - Custom `THORChainAPIError` class for API-specific errors ## Troubleshooting ### Tools Not Appearing in Claude 1. Verify the path in `claude_desktop_config.json` is absolute and correct 2. Ensure the project is built (`npm run build`) 3. Completely quit and restart Claude Desktop 4. Check Claude's logs: - macOS: `~/Library/Logs/Claude/mcp-server-thorchain.log` - Windows: `%APPDATA%\Claude\logs` ### Build Errors If you encounter build errors after updating dependencies: ```bash # Clean and rebuild rm -rf dist node_modules package-lock.json npm install npm run build ``` ### Connection Timeouts The server has a 5-second timeout for each API request. If you're experiencing frequent timeouts: 1. Check your internet connection 2. Verify the API providers are operational 3. The server will automatically try the fallback provider ## API Reference For detailed THORChain API documentation, see the [THORChain API Handbook](https://dev.thorchain.org/). ## License MIT ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## Links - [Model Context Protocol](https://modelcontextprotocol.io/) - [THORChain Documentation](https://docs.thorchain.org/) - [Nine Realms API](https://midgard.ninerealms.com)