BSC MCP Server

A Model Context Protocol (MCP) server for interacting with the Binance Smart Chain (BSC) network. This server enables LLMs to access blockchain data and perform queries on the BSC network.

Features

Get current block number
Retrieve block details by number or hash
Fetch transaction details
Get transaction receipts
Check wallet BNB balance
Check BEP-20 token balances
Create Four.meme tokens on BSC

Prerequisites

Node.js (v16 or higher)
npm or yarn

Installation

# Clone the repository
git clone https://github.com/ArcReactor9/BSC_MCP_SERVICES.git
cd BSC_MCP_SERVICES

# Install dependencies
npm install

# Build the project
npm run build

Usage

Configuration

By default, the server connects to the BSC mainnet. You can customize the RPC URL and set the private key (required for token creation) using environment variables:

# Windows
set BSC_RPC_URL=https://your-custom-bsc-rpc-url
set BSC_PRIVATE_KEY=your-private-key

# Linux/macOS
export BSC_RPC_URL=https://your-custom-bsc-rpc-url
export BSC_PRIVATE_KEY=your-private-key

Running the STDIO Server

The STDIO server is designed to be integrated with LLM clients that support the MCP protocol:

npm run start
# or
node dist/index.js

Running the HTTP/SSE Server

The HTTP/SSE server allows connections over HTTP using Server-Sent Events:

npm run start:http
# or
node dist/server-http.js

By default, the server runs on port 3000. You can customize the port using the PORT environment variable.

Client Examples

Several client implementations are provided to demonstrate how to use the BSC MCP server:

# Standard MCP client example
npm run client
# or
node dist/client-example.js

# HTTP client example
npm run client:http
# or
node dist/client-http-example.js

# Simple HTTP client example
npm run client:simple
# or
node dist/simple-http-client.js

API Endpoints (HTTP Server)

The HTTP server exposes the following endpoints:

Endpoint	Method	Description
`/`	GET	Server status check
`/mcp/hello`	POST	Get server information and available tools
`/mcp/tools/:toolName`	POST	Call a specific tool with arguments
`/mcp/sse`	GET	Server-Sent Events (SSE) endpoint for streaming connections

MCP Tools

This server exposes the following MCP tools:

Tool Name	Parameters	Description
`get-block-number`	None	Returns the current BSC block number
`get-block`	`blockHashOrNumber`: string or number	Returns block details for the given block hash or number
`get-transaction`	`txHash`: string	Returns transaction details for the given transaction hash
`get-transaction-receipt`	`txHash`: string	Returns transaction receipt for the given transaction hash
`get-balance`	`address`: string	Returns BNB balance for the given wallet address
`get-token-balance`	`tokenAddress`: string, `walletAddress`: string	Returns BEP-20 token balance for the given token and wallet address
`create-four-meme-token`	`name`: string, `symbol`: string, `initialSupply`: number, `decimals`: number, `ownerAddress`: string	Creates a new Four.meme token with specified parameters

Creating Four.meme Tokens

The BSC MCP server includes functionality to create new Four.meme tokens on the Binance Smart Chain. This allows users to easily deploy custom meme tokens with the following parameters:

name: The full name of the token (e.g., "Four Meme Token")
symbol: The token symbol (e.g., "4MEME")
initialSupply: The initial token supply to mint
decimals: The number of decimal places for the token (typically 18)
ownerAddress: The BSC address that will receive the initial token supply

Example using HTTP Client

// Example of creating a Four.meme token using the HTTP client
const client = new SimpleHttpClient('http://localhost:3000');

// Create a Four.meme token
const tokenResponse = await client.createFourMemeToken(
  'Four Pepe',   // Token name
  '4PEPE',       // Token symbol
  420690000000,  // Initial supply (before decimals)
  18,            // Decimals
  '0xYourWalletAddress'  // Owner address
);

console.log('Token creation response:', tokenResponse);

Integration with MCP.so

To properly display this service on mcp.so, please ensure that your repository contains the following:

A well-documented README.md (this file)
Code examples demonstrating how to use the tools
Clearly defined tool specifications

Development

Project Structure

BSC_MCP_SERVICES/
├── dist/               # Compiled JavaScript files
├── src/                # TypeScript source code
│   ├── bsc-service.ts  # BSC interaction service
│   ├── index.ts        # STDIO server implementation
│   ├── server-http.ts  # HTTP/SSE server implementation
│   └── ...             # Client examples and utilities
├── package.json        # Project dependencies and scripts
└── README.md           # Project documentation (this file)

Building the Project

npm run build

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Troubleshooting

Token Creation Issues

Ensure the BSC_PRIVATE_KEY environment variable is set correctly
Verify you have enough BNB to cover the gas fees for token deployment
Check that the owner address is a valid BSC address

Connection Issues

Verify the RPC URL is correct and accessible
Check network connectivity
Ensure the server is running on the expected port

Support

For any questions or support, please open an issue on the GitHub repository.

Integrations