Base Model Context Protocol (MCP) Server

Base MCP enables AI applications (such as Claude and Cursor) to interact with the Base Network and Coinbase API. Use cases are categorized into Developer, End-User, and Business applications.

Developer Use Cases

• Smart Contract Development: Deploy contracts via plain English descriptions, build contract function callers, create ERC20 tokens, or launch NFT collections.
• Everyday Applications: Build P2P payment apps (e.g., using MiniKit), group expense splitters, subscription managers, or donation buttons.
• DeFi Tools: Create Morpho vault viewers, DeFi position managers, yield comparison tools, auto-compound helpers, or lending dashboards.

End-User Use Cases

• Personal Finance: Build crypto earning apps (using OnchainKit's Earn component), savings trackers, or spare change savers.
• Family & Friends: Create shared family wallets, gift card senders, or chore reward systems.
• Shopping & Payments: Implement quick checkout buttons, digital product stores, or tipping tools.
• Community Projects: Build community fund pools, transparent charity platforms, or local event ticketing systems.

Business Use Cases

• Small Business Tools: Automate invoice payments, employee bonus distributions, vendor payments, or customer loyalty programs.

Execute advanced blockchain operations using these tools:

Transferring Funds

Use transfer-funds to move assets between addresses.

• destination: The recipient's wallet address.
• assetId: The symbol of the asset (e.g., ETH).
• amount: The quantity to transfer.

Deploying a Smart Contract

Use deploy-contract to deploy new contracts to the blockchain.

• contractName: The name of the contract.
• solidityInputJson: A JSON object containing the contract source code.
• solidityVersion: The compiler version (e.g., 0.8.20).
• constructorArgs: An array of arguments for the contract constructor.

/* transfer-funds parameters */
{
  "destination": "0x9876543210abcdef9876543210abcdef98765432",
  "assetId": "ETH",
  "amount": 0.01
}

/* deploy-contract parameters */
{
  "contractName": "ERC20Token",
  "solidityInputJson": "...",
  "solidityVersion": "0.8.20",
  "constructorArgs": ["ExampleToken", "EXT", "1000000000000000000000000"]
}

The library uses two primary types for representing NFT information:

1. NftData: A flexible, raw representation of NFT data that may contain optional fields such as contract, tokenId, title, name, description, tokenType, media (an array of gateway/raw objects), image, or arbitrary metadata.

2. FormattedNft: A standardized, flattened structure used for consistent consumption. It ensures that contractAddress, tokenId, title, description, tokenType, imageUrl, and metadata are all present and explicitly typed.

export type NftData = {
  contract?: { address?: string };
  tokenId?: string;
  id?: { tokenId?: string };
  title?: string;
  name?: string;
  description?: string;
  tokenType?: string;
  media?: Array<{ gateway?: string; raw?: string }>;
  image?: string;
  metadata?: Record<string, unknown>;
};

export type FormattedNft = {
  contractAddress: string;
  tokenId: string;
  title: string;
  description: string;
  tokenType: string;
  imageUrl: string;
  metadata: Record<string, unknown>;
};

The main function initializes and starts the Base MCP Server using the Model Context Protocol (MCP) over stdio transport. The server provides a set of tools derived from AgentKit that allow an AI agent to interact with the Base network, including Morpho, ERC20 tokens, NFTs, and on-ramp services.

Required Environment Variables

To run the server, you must provide the following environment variables:

Server Capabilities

• Tools: The server exposes tools via the ListToolsRequestSchema and handles execution via CallToolRequestSchema.
• Transport: Uses StdioServerTransport for communication.

// To run the server, ensure environment variables are set and call main()
import { main } from './src/main';

main().catch(console.error);

The init command provides an interactive CLI wizard to set up a new Model Context Protocol (MCP) server. It automates the configuration of environment variables and client-specific settings for applications like Claude and Cursor.

Workflow

1. API Keys: The CLI prompts for mandatory Coinbase Developer Platform (CDP) credentials:
   • CDP Key ID: Must be a valid UUID.
   • CDP Secret: The secret associated with your CDP key.
   • Mnemonic Phrase: An optional seed phrase. If left blank, the CLI will automatically generate a new one for you.
2. Additional Integrations: You can optionally select and configure keys for third-party tools:
   • OpenRouter (OPENROUTER_API_KEY)
   • Alchemy (NFTs) (ALCHEMY_API_KEY)
   • Flaunch (PINATA_JWT)
   • Neynar (Farcaster) (NEYNAR_API_KEY)
3. Client Configuration: Select which MCP clients to configure (e.g., Claude, Cursor). The CLI will then write the necessary configuration files to those applications using your provided keys.

You can configure the Base MCP server to work within the Cursor editor by updating the Cursor MCP configuration file located at ~/.cursor/mcp.json. This process adds a base server entry that runs via npx -y base-mcp@latest and injects necessary environment variables for authentication.

To configure the server, you must provide the following credentials via the configureCursor function:

• cdpKeyId: The Coinbase CDP Key ID.
• cdpSecret: The Coinbase CDP Private Key.
• mnemonicPhrase: The seed phrase for wallet access.
• optionalKeys: An object containing additional environment variables to be passed to the MCP server.

If a Cursor configuration already exists, the tool will prompt you before overwriting the existing base server configuration. If no configuration exists, it will create a new mcp.json file with the base server entry.

// Example usage of the configuration logic
await configureCursor({
  cdpKeyId: 'YOUR_CDP_KEY_ID',
  cdpSecret: 'YOUR_CDP_SECRET',
  mnemonicPhrase: 'YOUR_MNEMONIC_PHRASE',
  optionalKeys: {
    // Any additional environment variables
    CUSTOM_VAR: 'value'
  }
});

Manage contract interactions and specific token balances using these tools:

Calling Contract Functions

Use call_contract to execute read or write operations on any smart contract.

• contractAddress: The address of the target contract.
• functionName: The name of the function to call.
• functionArgs: An array of arguments to pass to the function.
• abi: A JSON object containing the contract's Application Binary Interface.

Managing ERC20 Tokens

• Check ERC20 Balance: Use erc20_balance with a contractAddress to see your balance of a specific token.
• Transfer ERC20 Tokens: Use erc20_transfer to move specific tokens.
  • contractAddress: The address of the ERC20 token contract.
  • toAddress: The recipient's address.
  • amount: The amount to transfer.

/* call_contract example */
call_contract({
  "contractAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "functionName": "balanceOf",
  "functionArgs": ["0x9876543210abcdef9876543210abcdef98765432"],
  "abi": { ... }
});

/* erc20_transfer example */
erc20_transfer({
  "contractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "toAddress": "0x9876543210abcdef9876543210abcdef98765432",
  "amount": "10"
});