# Bitgold MCP (Model Context Protocol)

A Model Context Protocol server that exposes [Bitgold Network](https://www.bitgold.network) blockchain operations as AI-callable tools. Bitgold is an independent public EVM chain derived from BSC v1.8.1 — it runs its own chain ID, native coin and validator set.

- Website: <https://www.bitgold.network>
- Docs: <https://docs.bitgold.network>
- Explorer (mainnet): <https://www.bitgold.live>
- Explorer (testnet): <https://testnet.bitgold.live>
- GitHub: <https://github.com/bitgold-network>

## Supported Networks

| Network          | Chain ID | Coin               | RPC                                                                                                                     | Explorer                     |
| ---------------- | -------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| Bitgold Mainnet  | 618      | BTG (18 decimals)  | `mainnet1-6.bitgold.network`, `mainnet-jp.bitgold.network`, `mainnet-sg.bitgold.network`, `rpc.bitgold.network`          | https://www.bitgold.live     |
| Bitgold Testnet  | 617      | tBTG (18 decimals) | `testnet1-3.bitgold.network`                                                                                            | https://testnet.bitgold.live |

Testnet tokens are available from the faucet at <https://faucet.bitgold.network>. Validators and staking are listed at <https://app.bitgold.network/staking/validators>.

Tool parameters accept either a network name (`bitgold-mainnet`, `bitgold`, `btg`, `bitgold-testnet`, `testnet`) or a chain ID (`618`, `617`). The default network is **Bitgold mainnet**; every write tool requires an explicit `network`.

## Core Modules

- **Blocks**: query block metadata and transaction hashes
- **Contracts**: read and write smart contracts, check whether an address is a contract
- **Network**: chain information and supported network list
- **NFT**: ERC721 / ERC1155 metadata and transfers
- **Tokens**: ERC20 information, balances, deployment
- **Transactions**: transaction lookup and gas estimation
- **Wallet**: address derivation, native coin transfers, ERC20 transfers and approvals
- **Confirm**: preview-then-confirm flow for every fund-moving operation

## Important Notes

**We do not recommend deploying this MCP server on the public internet.** (1) The SSE endpoint has **no authentication** — anyone who can reach it can use the server. (2) There is no centralized service that custodies private keys or funds. If you still need to deploy it publicly, put an **authentication layer** in front (API keys, JWT, or a reverse proxy with auth), or deploy a keyless instance that only exposes read-only tools.

**Credentials:** Prefer setting `PRIVATE_KEY` in the MCP server environment. Do not pass the private key in tool parameters when avoidable — it may be stored in conversation history, client logs, or request logs.

## Transfer Confirmation

Transfer tools (`transfer_native_token`, `transfer_erc20`, `approve_token_spending`, `transfer_nft`, `transfer_erc1155`, `write_contract`) use a **preview-then-confirm** flow by default so that no funds move until the user explicitly confirms.

- **Default behavior:** the tool returns a **preview** (recipient, amount, network, …) plus a short-lived **confirmToken**. No transaction is sent. Call **`confirm_transfer`** with that token and your `privateKey` to execute. The token expires after 5 minutes and is single-use.
- **Per call:** pass **`skipConfirmation: true`** to execute immediately.
- **Server-wide:** set **`BITGOLD_MCP_SKIP_TRANSFER_CONFIRMATION=true`** to execute every transfer immediately. Intended for headless or scripted environments.

Example flow:

1. Call `transfer_native_token` with `toAddress`, `amount`, `network` (and optionally `privateKey`). Do **not** set `skipConfirmation`.
2. The server returns `{ preview: { toAddress, amount, network }, confirmToken: "...", message: "..." }`.
3. Review the preview, then call `confirm_transfer` with `confirmToken` and `privateKey`.

## Integration

The configurations below use the published npm package (`@bitgold-network/mcp`). To run a local checkout instead, replace `command`/`args` with `"command": "node"` and `"args": ["/absolute/path/to/bitgold-mcp/dist/index.js"]` after `bun run build`.

### Cursor

Settings → MCP → Add new global MCP server:

```json
{
  "mcpServers": {
    "bitgold-mcp": {
      "command": "npx",
      "args": ["-y", "@bitgold-network/mcp@latest"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here (optional)",
        "BITGOLD_MCP_SKIP_TRANSFER_CONFIRMATION": "false"
      }
    }
  }
}
```

SSE mode:

```json
{
  "mcpServers": {
    "bitgold-mcp": {
      "command": "npx",
      "args": ["-y", "@bitgold-network/mcp@latest", "--sse"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here (optional)",
        "BITGOLD_MCP_SKIP_TRANSFER_CONFIRMATION": "false"
      }
    }
  }
}
```

### Claude Desktop

Settings → Developer → Edit Config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "bitgold-mcp": {
      "command": "npx",
      "args": ["-y", "@bitgold-network/mcp@latest"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "BITGOLD_MCP_SKIP_TRANSFER_CONFIRMATION": "false"
      }
    }
  }
}
```

Save the file and restart Claude Desktop. Example requests:

- "What is the latest block on Bitgold?"
- "Check the BTG balance of 0x6ea46bdb1f891086ddc6db61142e753b8e2ddf77"
- "Get the token info for 0x4afc633e7b6beb8e552ccddbe06cca3754991e9a"
- "Explain the EVM concept of gas"

### Claude Code / other CLI clients

```bash
claude mcp add bitgold -- npx -y @bitgold-network/mcp@latest
```

Or point the client at a local build (`node /path/to/bitgold-mcp/dist/index.js`). See [`examples`](./examples) for Anthropic SDK and LangChain clients.

## Local Development

### Prerequisites

- [Bun](https://bun.sh/) v1.2.10 or higher (used for build and tests)
- [Node.js](https://nodejs.org/en/download) v20 or higher (runtime)

### Quick Start

```bash
git clone https://github.com/bitgold-network/bitgold-mcp.git
cd bitgold-mcp

cp .env.example .env      # then edit .env
bun install
bun run build             # outputs dist/index.js (CJS)
bun run start             # stdio mode
bun run start --sse       # SSE mode on $PORT (default 3001)
```

Environment variables (see `.env.example`):

| Variable                             | Description                                        | Default |
| ------------------------------------ | -------------------------------------------------- | ------- |
| `PRIVATE_KEY`                        | Wallet private key (required for write operations) | —       |
| `LOG_LEVEL`                          | `DEBUG` / `INFO` / `WARN` / `ERROR`                | `INFO`  |
| `PORT`                               | HTTP port for SSE mode                             | `3001`  |
| `BITGOLD_MCP_SKIP_TRANSFER_CONFIRMATION` | Skip the preview/confirm flow                  | `false` |

### Available Scripts

- `bun dev` — stdio server with hot reload
- `bun run dev:sse` — SSE server with hot reload
- `bun run build` — build to `dist/`
- `bun run e2e` — E2E tests against Bitgold RPCs
- `bun run test` — MCP Inspector against the dev server
- `bun run typecheck` — `tsc --noEmit`
- `bun run check` — Biome lint + format

### Testing

```bash
bun run build
bun run e2e
```

Read-only tests run against public Bitgold RPCs. Write-path tests (native transfer, confirm execution) are skipped unless `PRIVATE_KEY` is set to a funded **testnet** key — fund it at <https://faucet.bitgold.network>. Never use a mainnet key for tests.

## Available Prompts and Tools

### Prompts

| Name                   | Description                                                         |
| ---------------------- | ------------------------------------------------------------------- |
| analyze_block          | Analyze a block and provide detailed information about its contents |
| analyze_transaction    | Analyze a specific transaction                                      |
| analyze_address        | Analyze a Bitgold address                                           |
| analyze_token          | Analyze an ERC20 or NFT token                                       |
| interact_with_contract | Get guidance on interacting with a smart contract                   |
| explain_evm_concept    | Get an explanation of an EVM concept                                |
| compare_networks       | Compare Bitgold mainnet and testnet                                 |

### Tools

| Name                         | Description                                                              |
| ---------------------------- | ------------------------------------------------------------------------ |
| get_block_by_hash            | Get block metadata by hash                                               |
| get_block_by_number          | Get block metadata by number                                             |
| get_latest_block             | Get the latest block                                                     |
| get_transaction              | Get detailed information about a transaction by hash                     |
| estimate_gas                 | Estimate the gas cost for a transaction                                  |
| get_chain_info               | Get chain information (chain ID, latest block, RPC URL)                  |
| get_supported_networks       | List supported networks                                                  |
| is_contract                  | Check if an address is a smart contract or an EOA                        |
| read_contract                | Call a view/pure function on a contract                                  |
| write_contract               | Call a state-changing function (preview + confirmToken by default)       |
| get_erc20_token_info         | Get ERC20 name, symbol, decimals and total supply                        |
| get_native_balance           | Get the BTG/tBTG balance of an address                                   |
| get_erc20_balance            | Get an ERC20 balance for an address                                      |
| create_erc20_token           | Deploy a new ERC20 token                                                 |
| get_address_from_private_key | Derive the address for a private key                                     |
| transfer_native_token        | Transfer BTG/tBTG (preview + confirmToken by default)                    |
| transfer_erc20               | Transfer ERC20 tokens (preview + confirmToken by default)                |
| approve_token_spending       | Approve an ERC20 spender (preview + confirmToken by default)             |
| get_nft_info                 | Get ERC721 metadata (name, symbol, token URI, owner)                     |
| get_erc1155_token_metadata   | Get the ERC1155 metadata URI for a token ID                              |
| transfer_nft                 | Transfer an ERC721 token (preview + confirmToken by default)             |
| transfer_erc1155             | Transfer ERC1155 tokens (preview + confirmToken by default)              |
| confirm_transfer             | Execute a pending preview using its confirmToken                         |

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes (`bun run check`, `bun run typecheck`, `bun run e2e`)
4. Push to your branch
5. Open a Pull Request

## License

MIT — see [LICENSE](LICENSE).

## Acknowledgements

This project is derived from [bnb-chain/bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp) and was reworked for Bitgold Network: BNB-specific modules (Greenfield storage, ERC-8004 agent registry, ENS resolution) were removed and the chain configuration, network tooling, documentation and tests were replaced with Bitgold equivalents.

It also builds on:

- [TermiX-official/bsc-mcp](https://github.com/TermiX-official/bsc-mcp) — original BSC MCP implementation
- [mcpdotdirect/evm-mcp-server](https://github.com/mcpdotdirect/evm-mcp-server) — EVM-compatible MCP server implementation