Base MCP Server 🔵

1# Base MCP Server 🔵
2 
3![OpenRouter Integration](public/OpenRouter.gif)
4 
5[![npm version](https://img.shields.io/npm/v/base-mcp.svg)](https://www.npmjs.com/package/base-mcp)
6[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7 
8A 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.
9 
10## Overview
11 
12This MCP server extends any MCP client's capabilities by providing tools to do anything on Base:
13 
14- Retrieve wallet addresses
15- List wallet balances
16- Transfer funds between wallets
17- Deploy smart contracts
18- Interact with Morpho vaults for onchain lending
19- Call contract functions
20- Onramp funds via [Coinbase](https://www.coinbase.com/developer-platform/products/onramp)
21- Manage ERC20 tokens
22- List and transfer NFTs (ERC721 and ERC1155)
23- Buy [OpenRouter](http://openrouter.ai/) credits with USDC
24- Resolve Farcaster usernames to Ethereum addresses
25 
26The server interacts with Base, powered by Base Developer Tools and [AgentKit](https://github.com/coinbase/agentkit).
27 
28## Extending Base MCP with 3P Protocols, Tools, and Data Sources
29 
30Base 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.
31 
32### Adding New Tools
33 
34If you want to add a new tool to the Base MCP server, follow these steps:
35 
361. Create a new directory in the `src/tools` directory for your tool
372. Implement the tool following the existing patterns:
38   - `index.ts`: Define and export your tools. Tools are defined as AgentKit ActionProviders.
39   - `schemas.ts`: Define input schemas for your tools
40   - `types.ts`: Define types required for your tools
41   - `utils.ts`: Utilities for your tools
423. Add your tool to the list of available tools in `src/main.ts`
434. Add documentation for your tool in the README.md
445. Add examples of how to use your tool in examples.md
456. Write tests for your tool
46 
47### Project Structure
48 
49The Base MCP server follows this structure for tools:
50 
51```
52src/
53├── tools/
54│   ├── [TOOL_NAME]/ <-------------------------- ADD DIR HERE
55│   │   ├── index.ts (defines and exports tools)
56│   │   ├── schemas.ts (defines input schema)
57│   └── utils/ (shared tool utilities)
58```
59 
60### Best Practices for Tool Development
61 
62When developing new tools for Base MCP:
63 
64- Follow the existing code style and patterns
65- Ensure your tool has a clear, focused purpose
66- Provide comprehensive input validation
67- Include detailed error handling
68- Write thorough documentation
69- Add examples demonstrating how to use your tool
70- Include tests for your tool
71 
72For more detailed information on contributing to Base MCP, including adding new tools and protocols, see the [CONTRIBUTING.md](CONTRIBUTING.md) file.
73 
74## Prerequisites
75 
76- Node.js (v16 or higher)
77- npm or yarn
78- Coinbase API credentials (API Key Name and Private Key)
79- A wallet seed phrase
80- Coinbase Project ID (for onramp functionality)
81- Alchemy API Key (required for NFT functionality)
82- Optional: OpenRouter API Key (for buying OpenRouter credits)
83 
84## Installation
85 
86### Option 1: Install from npm (Recommended)
87 
88```bash
89# Install globally
90npm install -g base-mcp
91 
92# Or install locally in your project
93npm install base-mcp
94```
95 
96Once the package is installed, you can configure clients with the following command:
97 
98```bash
99base-mcp --init
100```
101 
102### Option 2: Install from Source
103 
1041. Clone this repository:
105 
106   ```bash
107   git clone https://github.com/base/base-mcp.git
108   cd base-mcp
109   ```
110 
1112. Install dependencies:
112 
113   ```bash
114   npm install
115   ```
116 
1173. Build the project:
118 
119   ```bash
120   npm run build
121   ```
122 
1234. Optionally, link it globally:
124   ```bash
125   npm link
126   ```
127 
128## Configuration
129 
130Create a `.env` file with your credentials:
131 
132```
133# Coinbase API credentials
134# You can obtain these from the Coinbase Developer Portal: https://cdp.coinbase.com/
135COINBASE_API_KEY_NAME=your_api_key_name
136COINBASE_API_PRIVATE_KEY=your_private_key
137 
138# Wallet seed phrase (12 or 24 words)
139# This is the mnemonic phrase for your wallet
140SEED_PHRASE=your seed phrase here
141 
142# Coinbase Project ID (for onramp functionality)
143# You can obtain this from the Coinbase Developer Portal
144COINBASE_PROJECT_ID=your_project_id
145 
146# Alchemy API Key (required for NFT functionality)
147# You can obtain this from https://alchemy.com
148ALCHEMY_API_KEY=your_alchemy_api_key
149 
150# OpenRouter API Key (optional for buying OpenRouter credits)
151# You can obtain this from https://openrouter.ai/keys
152OPENROUTER_API_KEY=your_openrouter_api_key
153 
154# Chain ID (optional for Base Sepolia testnet)
155# Use 84532 for Base Sepolia testnet
156# You do not have to include this if you want to use Base Mainnet
157CHAIN_ID=your_chain_id
158 
159# Neynar API Key (required for Farcaster functionality)
160# You can obtain this from https://neynar.com
161NEYNAR_API_KEY=your_neynar_api_key
162```
163 
164## Testing
165 
166Test the MCP server to verify it's working correctly:
167 
168```bash
169npm test
170```
171 
172This script will verify that your MCP server is working correctly by testing the connection and available tools.
173 
174## Examples
175 
176See the [examples.md](examples.md) file for detailed examples of how to interact with the Base MCP tools through Claude.
177 
178## Integration with Claude Desktop
179 
180To add this MCP server to Claude Desktop:
181 
1821. Create or edit the Claude Desktop configuration file at:
183 
184   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
185   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
186   - Linux: `~/.config/Claude/claude_desktop_config.json`
187 
188You can easily access this file via the Claude Desktop app by navigating to Claude > Settings > Developer > Edit Config.
189 
1902. Add the following configuration:
191 
192   ```json
193   {
194     "mcpServers": {
195       "base-mcp": {
196         "command": "npx",
197         "args": ["-y", "base-mcp@latest"],
198         "env": {
199           "COINBASE_API_KEY_NAME": "your_api_key_name",
200           "COINBASE_API_PRIVATE_KEY": "your_private_key",
201           "SEED_PHRASE": "your seed phrase here",
202           "COINBASE_PROJECT_ID": "your_project_id",
203           "ALCHEMY_API_KEY": "your_alchemy_api_key",
204           "PINATA_JWT": "your_pinata_jwt",
205           "OPENROUTER_API_KEY": "your_openrouter_api_key",
206           "CHAIN_ID": "optional_for_base_sepolia_testnet"
207         },
208         "disabled": false,
209         "autoApprove": []
210       }
211     }
212   }
213   ```
214 
2153. Restart Claude Desktop for the changes to take effect.
216 
217## Available Tools
218 
219### get-address
220 
221Retrieves the address for your wallet.
222 
223Example query to Claude:
224 
225> "What's my wallet address?"
226 
227### list-balances
228 
229Lists all balances for your wallet.
230 
231Example query to Claude:
232 
233> "Show me my wallet balances."
234 
235### transfer-funds
236 
237Transfers funds from your wallet to another address.
238 
239Parameters:
240 
241- `destination`: The address to which to transfer funds
242- `assetId`: The asset ID to transfer
243- `amount`: The amount of funds to transfer
244 
245Example query to Claude:
246 
247> "Transfer 0.01 ETH to 0x1234567890abcdef1234567890abcdef12345678."
248 
249### deploy-contract
250 
251Deploys a smart contract to the blockchain.
252 
253Parameters:
254 
255- `constructorArgs`: The arguments for the contract constructor
256- `contractName`: The name of the contract to deploy
257- `solidityInputJson`: The JSON input for the Solidity compiler containing contract source and settings
258- `solidityVersion`: The version of the solidity compiler
259 
260Example query to Claude:
261 
262> "Deploy a simple ERC20 token contract for me."
263 
264### check-address-reputation
265 
266Checks the reputation of an address.
267 
268Parameters:
269 
270- `address`: The Ethereum address to check
271 
272Example query to Claude:
273 
274> "What's the reputation of 0x1234567890abcdef1234567890abcdef12345678?"
275 
276### get_morpho_vaults
277 
278Gets the vaults for a given asset on Morpho.
279 
280Parameters:
281 
282- `assetSymbol`: Asset symbol by which to filter vaults (optional)
283 
284Example query to Claude:
285 
286> "Show me the available Morpho vaults for USDC."
287 
288### call_contract
289 
290Calls a contract function on the blockchain.
291 
292Parameters:
293 
294- `contractAddress`: The address of the contract to call
295- `functionName`: The name of the function to call
296- `functionArgs`: The arguments to pass to the function
297- `abi`: The ABI of the contract
298- `value`: The value of ETH to send with the transaction (optional)
299 
300Example query to Claude:
301 
302> "Call the balanceOf function on the contract at 0x1234567890abcdef1234567890abcdef12345678."
303 
304### get_onramp_assets
305 
306Gets the assets available for onramping in a given country/subdivision.
307 
308Parameters:
309 
310- `country`: ISO 3166-1 two-digit country code string representing the purchasing user's country of residence
311- `subdivision`: ISO 3166-2 two-digit country subdivision code (required for US)
312 
313Example query to Claude:
314 
315> "What assets can I onramp in the US, specifically in New York?"
316 
317### onramp
318 
319Gets a URL for onramping funds via Coinbase.
320 
321Parameters:
322 
323- `amountUsd`: The amount of funds to onramp
324- `assetId`: The asset ID to onramp
325 
326Example query to Claude:
327 
328> "I want to onramp $100 worth of ETH."
329 
330### erc20_balance
331 
332Gets the balance of an ERC20 token.
333 
334Parameters:
335 
336- `contractAddress`: The address of the ERC20 contract
337 
338Example query to Claude:
339 
340> "What's my balance of the token at 0x1234567890abcdef1234567890abcdef12345678?"
341 
342### erc20_transfer
343 
344Transfers an ERC20 token to another address.
345 
346Parameters:
347 
348- `contractAddress`: The address of the ERC20 contract
349- `toAddress`: The address of the recipient
350- `amount`: The amount of tokens to transfer
351 
352Example query to Claude:
353 
354> "Transfer 10 USDC to 0x1234567890abcdef1234567890abcdef12345678."
355 
356### list_nfts
357 
358Lists NFTs owned by a specific address.
359 
360Parameters:
361 
362- `ownerAddress`: The address of the owner whose NFTs to list
363- `limit`: Maximum number of NFTs to return (default: 50)
364 
365Example query to Claude:
366 
367> "Show me the NFTs owned by 0x89A93a48C6Ef8085B9d07e46AaA96DFDeC717040."
368 
369### transfer_nft
370 
371Transfers an NFT to another address. Supports both ERC721 and ERC1155 standards.
372 
373Parameters:
374 
375- `contractAddress`: The address of the NFT contract
376- `tokenId`: The token ID of the NFT to transfer
377- `toAddress`: The address of the recipient
378- `amount`: The amount to transfer (only used for ERC1155, default: 1)
379 
380Example query to Claude:
381 
382> "Transfer my NFT with contract 0x3F06FcF75f45F1bb61D56D68fA7b3F32763AA15c and token ID 56090175025510453004781233574040052668718235229192064098345825090519343038548 to 0x1234567890abcdef1234567890abcdef12345678."
383 
384### buy_openrouter_credits
385 
386Buys OpenRouter credits with USDC.
387 
388Parameters:
389 
390- `amountUsd`: The amount of credits to buy, in USD
391 
392Example query to Claude:
393 
394> "Buy $20 worth of OpenRouter credits."
395 
396## Security Considerations
397 
398- The configuration file contains sensitive information (API keys and seed phrases). Ensure it's properly secured and not shared.
399- Consider using environment variables or a secure credential manager instead of hardcoding sensitive information.
400- Be cautious when transferring funds or deploying contracts, as these operations are irreversible on the blockchain.
401- When using the onramp functionality, ensure you're on a secure connection.
402- Verify all transaction details before confirming, especially when transferring funds or buying credits.
403 
404## Troubleshooting
405 
406If you encounter issues:
407 
4081. Check that your Coinbase API credentials are correct
4092. Verify that your seed phrase is valid
4103. Ensure you're on the correct network (Base Mainnet)
4114. Check the Claude Desktop logs for any error messages
412 
413## License
414 
415[MIT License](LICENSE)
416 
417## Contributing
418 
419Contributions are welcome! Please feel free to submit a Pull Request.
420 
421For detailed guidelines on contributing to Base MCP, including:
422 
423- Reporting bugs
424- Suggesting enhancements
425- Development setup
426- Coding standards
427- **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)
428- Testing requirements
429- Documentation standards
430 
431Please refer to our comprehensive [CONTRIBUTING.md](CONTRIBUTING.md) guide.
432 
433Basic contribution steps:
434 
4351. Fork the repository
4362. Create your feature branch (`git checkout -b feature/amazing-feature`)
4373. Commit your changes (`git commit -m 'Add some amazing feature'`)
4384. Push to the branch (`git push origin feature/amazing-feature`)
4395. Open a Pull Request
440 
441Please make sure your code follows the existing style and includes appropriate tests.
442