Beeper MCP

1# beeper-mcp
2 
3A backend service for executing beeper transactions on Binance Smart Chain (BSC). This service provides a set of tools for interacting with the BSC blockchain, including balance checking, balance transfers, token transfers, token swaps in Pancakeswap and beeper reward claims.
4 
5## Features
6 
7- Get BNB and token balances
8- Transfer BNB and tokens
9- Swap tokens in Pancakeswap
10- Get token prices
11- Buy and sell tokens
12- Claim rewards of beeper tokens
13- Manage default wallet and token addresses
14 
15## Prerequisites
16 
17- Python >=3.10
18- Access to BSC network (mainnet or testnet)
19- Wallet account and private key
20 
21## Environment Variables
22 
23Create a `.env` file in the project root with the following variables:
24 
25```env
26BEEPER_CHAIN=<bsc or bsc-testnet>
27BEEPER_ACCOUNT=<your-wallet-address>
28BEEPER_SECRET_KEY=<your-private-key>
29BEEPER_TARGET_TOKEN=<default-token-address>  # Optional
30```
31 
32## API Endpoints
33 
34The service exposes the following MCP tools:
35 
36### Wallet and Token Management
37- `get_default_wallet_address() -> str`: Get the default wallet address
38- `get_default_token_address() -> str`: Get the default token address
39- `switch_default_token_address(new_token_address: str) -> str`: Switch to a new default token address
40 
41### Balance Operations
42- `get_balance(address: str) -> str`: Get BNB balance of an address
43- `get_token_balance(address: str, token_address: str) -> str`: Get token balance of an address
44 
45### Transfer Operations
46- `transfer(recipient_address: str, amount: Decimal = 0.01) -> dict`: Transfer BNB to an address
47- `transfer_token(recipient_address: str, token_address: str, amount: Decimal = 0.01) -> dict`: Transfer tokens to an address
48 
49### Trading Operations
50- `swap_token(token_in: str, token_out: str, amount: Decimal = 0.01) -> dict`: Swap between tokens
51- `get_token_price(token_address: str) -> float`: Get token price in BNB
52- `buy_token(token_address: str, amount: Decimal = 0.01) -> dict`: Buy tokens with BNB
53- `sell_token(token_address: str, amount: Decimal = 0.01) -> dict`: Sell tokens for BNB
54 
55### Reward Operations
56- `claim_rewards(token_address: str) -> dict`: Claim rewards for a token
57 
58## Running the Service
59 
60```bash
61git clone https://github.com/unibaseio/beeper-mcp.git
62cd beeper-mcp
63# start server over stdio
64uv run src/beeper_mcp/server.py 
65```
66 
67+ start using sse
68 
69The sse service will start on port 8000 by default. You can specify a different port using the `--port` argument:
70 
71```bash
72uv run src/beeper_mcp/server.py --port 8008 --transport=sse
73```
74 
75### Configuration on Claude/Windsurf/Cursor/Cline
76 
77```json
78{
79  "mcpServers": {
80    "beeper": {
81      "command": "uv",
82      "args": [
83        "--directory",
84        "path/to/beeper-mcp",
85        "run", 
86        "src/beeper_mcp/server.py"
87        ],
88      "env": {
89        "BEEPER_ACCOUNT": "your account, 0x...",
90        "BEEPER_SECRET_KEY": "your private key or in .env",
91        "BEEPER_TARGET_TOKEN": "default token address",
92        "BEEPER_CHAIN": "chain type <bsc/bsc-testnet>"
93      }
94    }
95  }
96}
97```
98 
99## Notes
100 
101- All amounts are in native units (e.g., BNB, tokens)
102- Token addresses should be provided in the correct format
103- Make sure you have sufficient BNB for gas fees
104- The service supports both BSC mainnet and testnet
105- All operations return detailed response objects with transaction hashes and status information
106- The service includes built-in error handling and status tracking for transactions
107 
108 
109## Usage
110 
111call functions in llm chat
112 
113+ show wallet and buy tokens
114 
115![show wallet and buy tokens](./asset/buy.png)
116 
117+ sell tokens
118 
119![sell tokens](./asset/sell.png)