# TON BLOCKCHAIN MCP
A Model Context Protocol (MCP) server for natural language interaction with the [TON blockchain](http://ton.org/).
## Features
- **Natural Language Processing**: Understand complex blockchain queries in plain English
- **Trading Analysis**: Analyze trading patterns, profitability, and strategies
- **Hot Trends Detection**: Find trending tokens, active pools, and high-activity accounts
- **Forensics & Compliance**: Conduct blockchain investigations and compliance checks
- **Real-time Data**: Access live TON blockchain data through TON API
## Quick Start
### Prerequisites
- Python 3.10+
- TON API key from [TONAPI](https://tonconsole.com/tonapi)
### Environment Configuration (.env)
To securely provide sensitive configuration (such as your TON API key), create a `.env` file in the project root directory. This file will be loaded automatically if present.
**Example `.env` file:**
```
TON_API_KEY=YOUR_TON_API_KEY
```
### Installation
1. Clone the repository:
```bash
git clone https://github.com/devonmojito/ton-blockchain-mcp.git
cd ton-blockchain-mcp
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
---
## Using TON MCP Server with Claude Desktop
You can easily use this MCP server with Claude Desktop for natural language blockchain queries. Below are some example use cases:
**Scam Detection Example:**
**Analyze Address Example:**
**Get Transaction Details Example:**
**Analyze Trading Patterns Example:**
### Claude Desktop Configuration Example
To use this MCP server with Claude Desktop, add the following to your Claude Desktop config:
* You might need to replace the Python env setup with your own.
```json
{
"mcpServers":
{
"ton-mcp-server":
{
"command": "/Users/devon/ton-mcp/ton-blockchain-mcp/venv/bin/python",
"args":
[
"-m",
"tonmcp.mcp_server"
],
"cwd": "/Users/devon/ton-mcp/ton-blockchain-mcp/src",
"env":
{
"PYTHONPATH": "/Users/devon/ton-mcp/ton-blockchain-mcp/src"
},
"stdio": true
}
}
}
```
---
### Natural Language Examples
- "What's the balance of address EQD1234...?"
- "Find hot trading pairs in the last hour"
- "Analyze trading patterns for this wallet"
- "Show suspicious activity for address ABC"
- "Trace money flow from this address"
## MCP Tools & System Prompts Documentation
### Tools
#### analyze_address
Analyze a TON address for its balance, jetton holdings, NFTs, and recent activity. Optionally performs deep forensic analysis if `deep_analysis` is True. Use for questions about account overview, holdings, or activity.
**Parameters:**
- `address` (str): TON address to analyze
- `deep_analysis` (bool, optional): Enable deep forensic analysis
#### get_transaction_details
Get details and analysis for a specific TON blockchain transaction by its hash. Use for questions about a particular transaction, its participants, value, or type.
**Parameters:**
- `tx_hash` (str): Transaction hash
#### find_hot_trends
Find trending tokens, pools, or accounts on the TON blockchain for a given timeframe and category. Use for questions about what's hot, trending, or popular on TON.
**Parameters:**
- `timeframe` (str, optional): Time period (e.g., 1h, 24h, 7d)
- `category` (str, optional): Type of trends (tokens, pools, accounts)
#### analyze_trading_patterns
Analyze trading patterns for a TON address over a specified timeframe. Use for questions about trading activity, frequency, jetton transfers, or DEX swaps for an account.
**Parameters:**
- `address` (str): TON address
- `timeframe` (str, optional): Time period (e.g., 24h)
#### get_ton_price
Get the current real-time TON price in the specified currency (default: USD) and recent price changes. Use this tool whenever you need the latest TON price for calculations, analysis, or reporting.
**Parameters:**
- `currency` (str, optional): The fiat or crypto currency to get the TON price in (default: 'usd').
#### get_jetton_price
Get the current price and recent changes for specified jetton tokens (not TON) in the given currency. Provide a list of jetton master addresses as tokens. Use this tool to fetch real-time prices for any token except TON.
**Parameters:**
- `tokens` (list of str): List of jetton master addresses to get prices for (excluding 'ton').
- `currency` (str, optional): The fiat or crypto currency to get the price in (default: 'usd').
### System Prompts
- `trading_analysis`: Generate trading analysis prompts
- `forensics_investigation`: Generate forensics prompts
- `trend_analysis`: Generate trend analysis prompts
## Contributing
1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
For support, please open an issue on GitHub
**⚠️ WARNING: This project is in Beta. Do not trust any numbers provided by the LLM model. Nothing in this project constitutes financial advice. Use at your own risk.**
