@outblock/flow-mcp

Flow blockchain tools for Model Context Protocol (MCP). This package provides a set of tools for interacting with the Flow blockchain through the Model Context Protocol.

Features

• Get FLOW balance for any address
• Get token balance for any Flow token
• Get COA account information
• Get contract source code
• Get detailed account information including storage stats

Installation

# Using npm
npm install @outblock/flow-mcp

# Using bun
bun add @outblock/flow-mcp

MCP Configuration

To use this tool with Claude, add the following to your MCP configuration:

{
  "mcpServers": {
    "flow": {
      "command": "npx",
      "args": ["-y", "@outblock/flow-mcp"]
    }
  }
}

You can find your MCP configuration at:

• macOS: ~/Library/Application Support/Claude/mcp.json
• Windows: %APPDATA%/Claude/mcp.json
• Linux: ~/.config/Claude/mcp.json

After adding the configuration, restart Claude to load the new MCP server.

Tools

Flow Balance

Get the FLOW balance for any address:

{
  name: 'get_flow_balance',
  input: {
    address: string,
    network?: 'mainnet' | 'testnet'
  }
}

Account Info

Get detailed account information:

{
  name: 'get_account_info',
  input: {
    address: string,
    network?: 'mainnet' | 'testnet'
  }
}

Token Balance

Get balance for any Flow token:

{
  name: 'get_token_balance',
  input: {
    address: string,
    network?: 'mainnet' | 'testnet'
  }
}

COA Account

Get COA account information:

{
  name: 'get_coa_account',
  input: {
    address: string,
    network?: 'mainnet' | 'testnet'
  }
}

Get Contract

Get contract source code:

{
  name: 'get_contract',
  input: {
    address: string,
    contractName: string,
    network?: 'mainnet' | 'testnet'
  }
}

📂 Project Structure

flow-mcp/
├── src/
│   ├── tools/          # MCP tools implementation
│   │   ├── flowBalance/    # Flow balance tool
│   │   ├── accountInfo/    # Account info tool
│   │   ├── tokenBalance/   # Token balance tool
│   │   ├── coaAccount/     # COA account tool
│   │   └── getContract/    # Contract source tool
│   ├── utils/          # Shared utilities
│   ├── prompts/        # MCP prompts
│   ├── types/          # Type definitions
│   └── bin/           # CLI implementation
├── biome.json         # Linting configuration
├── tsconfig.json      # TypeScript configuration
└── package.json       # Project dependencies

🛠️ Development

This project uses FastMCP for development and testing. FastMCP provides a streamlined development experience for MCP servers.

# Install dependencies
bun install

# Format code
bun run format

# Run tests
bun test

# Run development server
bun run dev

# Inspect the server
bun run inspect

# Build
bun run build

To add your development MCP server to Claude Desktop:

1. Build the project:

   bun run build
   

2. Add to your Claude Desktop config:

   // You only need the argument if you need to pass arguments to your server
   {
     "mcpServers": {
       "your-server-name": {
         "command": "node",
         "args": ["/path/to/your/project/dist/main.js", "some_argument"]
       }
     }
   }
   

Creating New Tools

The project includes a script to help create new MCP tools:

bun run scripts/create-tool.ts <tool-name>

This will:

1. Create a new tool directory under src/tools/<tool-name>
2. Generate the basic tool structure including:
   • index.ts (main implementation)
   • schema.ts (JSON schema for tool parameters)
   • test.ts (test file)
3. Update the tools index file to export the new tool

Example:

bun run scripts/create-tool.ts weather

Commit Message Format

• feat: New feature (bumps minor version)
• fix: Bug fix (bumps patch version)
• BREAKING CHANGE: Breaking change (bumps major version)

📜 Version Management

This project uses standard-version for automated version management. Run bun run release to create a new version.

📦 Publishing to npm

1. Ensure you're logged in to npm:

   npm login
   

2. Build the project:

   bun run build
   

3. Publish the package:

   npm publish
   

Remember to update the version number using bun run release before publishing new versions.

License

MIT License - see LICENSE for details.

Contributing

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