Stargate Bridge MCP

1# Stargate Bridge MCP
2 
3An MCP server that enables cross-chain token transfers via the Stargate protocol.
4 
5![GitHub License](https://img.shields.io/github/license/kukapay/stargate-bridge-mcp) 
6![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
7![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
8 
9 
10## Features
11 
12- **Chain Discovery**: List all supported blockchains with key details.
13- **Token Discovery**: Find bridgeable tokens across chains.
14- **Quote Fetching**: Get real-time bridge quotes with fees, estimates, and transaction steps.
15- **Automated Bridging**: Execute transfers with automatic signing and broadcasting using your private key.
16- **MCP Integration**: Fully compliant with MCP spec for easy use in Claude, Cursor, or other MCP clients.
17 
18| Tool | Description | Key Parameters |
19|------|-------------|----------------|
20| `list_chains` | Lists supported chains in a sorted Markdown table. | None |
21| `list_bridgeable_tokens` | Lists bridgeable destinations for a source token. | `src_chain_key`, `src_token` |
22| `get_quotes` | Fetches detailed quotes for a bridge route. | `src_chain_key`, `dst_chain_key`, `src_token`, `dst_token`, `src_amount`, `dst_amount_min` (optional: `src_address`, `dst_address`) |
23| `bridge_transfer` | Executes a bridge transfer (uses first quote). | `src_chain_key`, `dst_chain_key`, `src_token`, `dst_token`, `src_amount`, `dst_amount_min` (optional: `dst_address`) |
24 
25## Known Limitations
26 
27Currently supports cross-chain bridging only between EVM-compatible chains (e.g., Ethereum, Polygon, Arbitrum). Non-EVM chains like Solana are planned for future support.
28## Quick Start
29 
30### Prerequisites
31- Python 3.10+
32- [uv](https://docs.astral.sh/uv/) for dependency management (recommended; fallback to pip)
33- A `.env` file with your Ethereum-compatible private key (e.g., `PRIVATE_KEY=0x...`). **Never commit this file!**
34 
35### Installation
361. Clone the repo:
37   ```
38   git clone https://github.com/kukapay/stargate-bridge-mcp.git
39   cd stargate-bridge-mcp
40   ```
41 
422. Install dependencies with uv:
43   ```
44   uv sync  # Or uv add requests web3 python-dotenv "mcp[cli]"
45   ```
46 
473. Install to Claude Desktop:
48 
49   Install the server as a Claude Desktop application:
50   ```bash
51   uv run mcp install main.py --name "Stargate Bridge"
52   ```
53 
54   Configuration file as a reference:
55 
56   ```json
57   {
58      "mcpServers": {
59          "Stargate Bridge": {
60              "command": "uv",
61              "args": [ "--directory", "/path/to/stargate-bridge-mcp", "run", "main.py" ],
62              "env": { "PRIVATE_KEY": "your_private_key"}
63          }
64      }
65   }
66   ```
67   Replace `/path/to/stargate-bridge-mcp` with your actual installation path, and replace `your_private_key` with your wallet private key.
68 
69## Usage Examples
70 
71These examples simulate interactions in an MCP client like Claude Desktop. Each includes a natural language prompt, the tool call, and sample output.
72 
73### 1. List Supported Chains
74**Prompt**: "Show me all the chains supported by Stargate for bridging."
75 
76**Tool Call**: `list_chains()`
77 
78**Sample Output** (Markdown table, sorted by chainKey):
79```
80| chainKey | Name | Chain Type | Chain ID | Native Symbol |
81|----------|------|------------|----------|---------------|
82| arbitrum | Arbitrum One | evm | 42161 | ETH |
83| avalanche | Avalanche C-Chain | evm | 43114 | AVAX |
84| base | Base | evm | 8453 | ETH |
85| bnbchain | BNB Smart Chain | evm | 56 | BNB |
86| ethereum | Ethereum | evm | 1 | ETH |
87| ... (additional chains)
88```
89 
90### 2. List Bridgeable Tokens
91**Prompt**: "What tokens can I bridge USDC from Ethereum to other chains?"
92 
93**Tool Call**: `list_bridgeable_tokens("ethereum", "0xA0b86a33E641b9E649bEe6b2D5D7b5b4D8f3a0a")` (USDC on Ethereum)
94 
95**Sample Output** (Markdown table, sorted by Chain Key):
96```
97| Chain Key | Symbol | Address |
98|-----------|--------|---------|
99| arbitrum | USDC | 0xA0b86a33E641b9E649bEe6b2D5D7b5b4D8f3a0a |
100| avalanche | USDC | 0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E |
101| polygon | USDC | 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 |
102| ... (additional destinations)
103```
104 
105### 3. Get Bridge Quotes
106**Prompt**: "Get quotes for bridging 10 USDC from Ethereum to Polygon with 1% slippage."
107 
108**Tool Call**: `get_quotes("ethereum", "polygon", "0xA0b86a33E641b9E649bEe6b2D5D7b5b4D8f3a0a", "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", 10.0, 9.9)`
109 
110**Sample Output** (Concise Markdown):
111```
112# Stargate Bridge Quotes
113 
114**Src**: ETHEREUM USDC 10.0 → **Dst**: POLYGON USDC
115 
116## Quote 1 (stargate/v2/taxi)
117- **Expected Receive**: 9.98 USDC
118- **Min Receive**: 9.90 USDC
119- **Est. Time**: 180s
120- **Fees**:
121  - 0.000050 ETH on ethereum (message)
122 
123### Steps
124  - **Step 1 (bridge)**: To 0x77b204... | Value: 0.0100 ETH | Data: 0xc7c7f5b3...
125 
126**Note**: Use `bridge_transfer` to execute (uses first quote).
127```
128 
129### 4. Execute Bridge Transfer
130**Prompt**: "Execute the bridge for 10 USDC from Ethereum to Polygon."
131 
132**Tool Call**: `bridge_transfer("ethereum", "polygon", "0xA0b86a33E641b9E649bEe6b2D5D7b5b4D8f3a0a", "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", 10.0, 9.9)`
133 
134**Sample Output** (On success; Markdown):
135```
136## Bridge Transfer Successful
137 
138Transaction hashes:
139- Step 1: 0x1234abcd...efgh5678
140```
141 
142**Note**: If it fails (e.g., insufficient gas), returns an error like `# Error\nStep 1 failed (reverted).`
143 
144## License
145 
146MIT License - see [LICENSE](LICENSE) for details.