Base MCP Server 🔵

A Model Context Protocol (MCP) server that provides onchain tools for AI applications like Claude Desktop and Cursor, allowing them to interact with the Base Network and Coinbase API.

Overview

This MCP server extends any MCP client's capabilities by providing tools to do anything on Base:

• Retrieve wallet addresses
• List wallet balances
• Transfer funds between wallets
• Deploy smart contracts
• Interact with Morpho vaults for onchain lending
• Call contract functions
• Onramp funds via Coinbase
• Manage ERC20 tokens
• List and transfer NFTs (ERC721 and ERC1155)
• Buy OpenRouter credits with USDC
• Resolve Farcaster usernames to Ethereum addresses

The server interacts with Base, powered by Base Developer Tools and AgentKit.

Extending Base MCP with 3P Protocols, Tools, and Data Sources

Base MCP is designed to be extensible, allowing you to add your own third-party protocols, tools, and data sources. This section provides an overview of how to extend the Base MCP server with new capabilities.

Adding New Tools

If you want to add a new tool to the Base MCP server, follow these steps:

1. Create a new directory in the src/tools directory for your tool
2. Implement the tool following the existing patterns:
   • index.ts: Define and export your tools. Tools are defined as AgentKit ActionProviders.
   • schemas.ts: Define input schemas for your tools
   • types.ts: Define types required for your tools
   • utils.ts: Utilities for your tools
3. Add your tool to the list of available tools in src/main.ts
4. Add documentation for your tool in the README.md
5. Add examples of how to use your tool in examples.md
6. Write tests for your tool

Project Structure

The Base MCP server follows this structure for tools:

src/
├── tools/
│   ├── [TOOL_NAME]/  "What assets can I onramp in the US, specifically in New York?"

### onramp

Gets a URL for onramping funds via Coinbase.

Parameters:

- `amountUsd`: The amount of funds to onramp
- `assetId`: The asset ID to onramp

Example query to Claude:

> "I want to onramp $100 worth of ETH."

### erc20_balance

Gets the balance of an ERC20 token.

Parameters:

- `contractAddress`: The address of the ERC20 contract

Example query to Claude:

> "What's my balance of the token at 0x1234567890abcdef1234567890abcdef12345678?"

### erc20_transfer

Transfers an ERC20 token to another address.

Parameters:

- `contractAddress`: The address of the ERC20 contract
- `toAddress`: The address of the recipient
- `amount`: The amount of tokens to transfer

Example query to Claude:

> "Transfer 10 USDC to 0x1234567890abcdef1234567890abcdef12345678."

### list_nfts

Lists NFTs owned by a specific address.

Parameters:

- `ownerAddress`: The address of the owner whose NFTs to list
- `limit`: Maximum number of NFTs to return (default: 50)

Example query to Claude:

> "Show me the NFTs owned by 0x89A93a48C6Ef8085B9d07e46AaA96DFDeC717040."

### transfer_nft

Transfers an NFT to another address. Supports both ERC721 and ERC1155 standards.

Parameters:

- `contractAddress`: The address of the NFT contract
- `tokenId`: The token ID of the NFT to transfer
- `toAddress`: The address of the recipient
- `amount`: The amount to transfer (only used for ERC1155, default: 1)

Example query to Claude:

> "Transfer my NFT with contract 0x3F06FcF75f45F1bb61D56D68fA7b3F32763AA15c and token ID 56090175025510453004781233574040052668718235229192064098345825090519343038548 to 0x1234567890abcdef1234567890abcdef12345678."

### buy_openrouter_credits

Buys OpenRouter credits with USDC.

Parameters:

- `amountUsd`: The amount of credits to buy, in USD

Example query to Claude:

> "Buy $20 worth of OpenRouter credits."

## Security Considerations

- The configuration file contains sensitive information (API keys and seed phrases). Ensure it's properly secured and not shared.
- Consider using environment variables or a secure credential manager instead of hardcoding sensitive information.
- Be cautious when transferring funds or deploying contracts, as these operations are irreversible on the blockchain.
- When using the onramp functionality, ensure you're on a secure connection.
- Verify all transaction details before confirming, especially when transferring funds or buying credits.

## Troubleshooting

If you encounter issues:

1. Check that your Coinbase API credentials are correct
2. Verify that your seed phrase is valid
3. Ensure you're on the correct network (Base Mainnet)
4. Check the Claude Desktop logs for any error messages

## License

[MIT License](LICENSE)

## Contributing

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

For detailed guidelines on contributing to Base MCP, including:

- Reporting bugs
- Suggesting enhancements
- Development setup
- Coding standards
- **Adding new tools, protocols, and data sources** (see also the [Extending Base MCP](#extending-base-mcp-with-3p-protocols-tools-and-data-sources) section above)
- Testing requirements
- Documentation standards

Please refer to our comprehensive [CONTRIBUTING.md](CONTRIBUTING.md) guide.

Basic contribution steps:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Please make sure your code follows the existing style and includes appropriate tests.