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)
npm install -g @missionsquad/mcp-thorchain
From Source
# 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
{
"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:
- Completely quit Claude Desktop (Cmd+Q on macOS, or via System Tray on Windows)
- Reopen Claude Desktop
- The THORChain tools should now be available
Testing with MCP Inspector
You can test the server without Claude Desktop using the MCP Inspector:
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:
{
"txid": "DC85CB537CB6082F61270D70C4058BB111475BCDC403E6E42AAF2106D067E1B4"
}
2. get-address-history
Retrieve transaction history for a blockchain address.
Parameters:
address(string, required): Blockchain address to querylimit(number, optional): Maximum transactions to return (default: 10, max: 50)offset(number, optional): Pagination offset (default: 0)
Example:
{
"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:
{
"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:
{
"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
npm run build
Watch Mode
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 SDKzod@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
THORChainAPIErrorclass for API-specific errors
Troubleshooting
Tools Not Appearing in Claude
- Verify the path in
claude_desktop_config.jsonis absolute and correct - Ensure the project is built (
npm run build) - Completely quit and restart Claude Desktop
- Check Claude's logs:
- macOS:
~/Library/Logs/Claude/mcp-server-thorchain.log - Windows:
%APPDATA%\Claude\logs
- macOS:
Build Errors
If you encounter build errors after updating dependencies:
# 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:
- Check your internet connection
- Verify the API providers are operational
- The server will automatically try the fallback provider
API Reference
For detailed THORChain API documentation, see the THORChain API Handbook.
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.