内容
# Tezos MCP ꜩ
用于 Tezos 区块链的模型上下文协议服务器。让 claude 通过标准 MCP 工具与 Tezos 进行原生交互。
## 功能
**读取操作**（无需密钥）
- 查询余额、合约存储、交易历史
- 获取区块信息和网络常量
- 适用于主网、shadownet、ghostnet
**写入操作**（需要私钥）
- 发送交易和部署合约
- 调用合约入口点
- 签名/验证消息，生成地址
**支持的网络**
- mainnet - 生产环境
- shadownet - 主要测试网（推荐）
- ghostnet - 遗留测试网（已弃用，迁移到 shadownet）
## 设置
### 快速开始（只读）
无需 pytezos 编译即可立即工作：
```bash
python -m venv .venv
source .venv/bin/activate # windows: .venv\Scripts\activate
pip install "mcp>=1.0.0" "httpx>=0.27.0"
# register with claude
claude mcp add --transport stdio tezos-readonly -- python server_readonly.py
```
### 完整设置（带交易）
需要 pytezos 进行写入操作。在 Windows 上，使用 conda 最简单：
```bash
conda create -n tezos-mcp python=3.11
conda activate tezos-mcp
pip install "mcp>=1.0.0" "httpx>=0.27.0"
conda install -c conda-forge pytezos
claude mcp add --transport stdio tezos -- python server.py
```
如果 conda 不可用，请参阅 `INSTALL_WINDOWS.md` 获取 wsl2/docker 选项。
## 用法
```bash
claude
```
然后：
```
> /mcp # verify server connected
> what's the balance of tz1VSUr8... ? # query balance
> show recent ops for tz1... # transaction history
> latest block on shadownet # block info
```
对于交易（需要 TEZOS_PRIVATE_KEY 环境变量）：
```
> send 1 xtz to tz1... on shadownet
> deploy this contract to shadownet
> call mint on contract KT1...
```
### 使用技能
```
> /tezos help me build an fa2 token
> /tezos optimize gas in this contract
> /tezos security checklist
```
## 配置
### 环境变量
```bash
# private key for transactions
export TEZOS_PRIVATE_KEY="edsk..."
# optional: custom rpc nodes
export TEZOS_MAINNET_NODE="https://your-node.com"
export TEZOS_SHADOWNET_NODE="https://your-node.com"
```
或使用 `.env` 文件（参见 `.env.example`）。
### 默认端点
从 [teztnets.com](https://teztnets.com/) 和官方文档验证：
- mainnet: `https://mainnet.api.tez.ie`
- shadownet: `https://rpc.shadownet.teztnets.com`
- ghostnet: `https://rpc.ghostnet.teztnets.com`
## 可用工具
### 读取工具
| tool | params | example |
|------|--------|---------|
| get_balance | address, network | balance of tz1... on mainnet |
| get_contract_storage | contract_address, network | storage of KT1... |
| get_operations | address, limit, network | last 10 ops for tz1... |
| get_block_info | level (optional), network | latest block info |
| get_network_info | network | network constants |
### 写入工具
| tool | params | notes |
|------|--------|-------|
| send_transaction | destination, amount_mutez, network | requires private key |
| call_contract | contract, entry_point, params, amount | execute contract |
| originate_contract | code, storage, network | deploy new contract |
| sign_message | message | cryptographic signing |
| verify_signature | message, signature, pubkey | verify signed message |
| generate_address | mnemonic (optional) | create new address |
## 示例
### 检查余额
```python
get_balance(
address="tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb",
network="mainnet"
)
```
### 发送交易
```python
send_transaction(
destination="tz1...",
amount_mutez=1_000_000, # 1 xtz
network="shadownet"
)
```
### 部署合约
```python
originate_contract(
code='<michelson_code>',
storage='42',
network="shadownet"
)
```
有关更多模式，请参见 `examples.md`。
## 项目结构
```
tezos-mcp/
├── server.py # full mcp server (13 tools)
├── server_readonly.py # read-only version (4 tools)
├── pyproject.toml # dependencies
├── README.md # this file
├── QUICKSTART.md # 5min setup guide
├── SOURCES.md # verified endpoints & docs
├── examples.md # usage patterns
├── INSTALL_WINDOWS.md # windows installation
├── .env.example # config template
└── .claude/
└── skills/
└── tezos/
└── SKILL.md # development guidance
```
## 安全
- 永远不要提交私钥
- 使用 shadownet 进行测试
- 在主网部署之前审计合约
- 使用环境变量存储密钥
- 所有端点均已针对官方来源进行验证
有关文档验证，请参见 `SOURCES.md`。
## 资源
使用的官方文档：
- [tezos docs](https://docs.tezos.com/)
- [testnet registry](https://teztnets.com/)
- [tzkt api](https://api.tzkt.io/)
- [shadownet faucet](https://faucet.shadownet.teztnets.com/)
- [pytezos](https://pytezos.org/)
- [ligo](https://ligolang.org/)
## 贡献
此实现专门引用官方 Tezos 文档。所有 RPC 端点和网络配置均已针对 [teztnets.com](https://teztnets.com/) 和 [docs.tezos.com](https://docs.tezos.com/) 进行验证。
## 许可证
MIT
