Story MCP hub

You run two MCP servers to empower AI agents with Story Protocol capabilities: a StoryScan MCP Server for blockchain data queries and a Story SDK MCP Server for interacting with Story Protocol’s SDK tools. These MCP servers expose a collection of tools your agents can call to fetch blockchain data, manage IP assets, handle licenses and revenue, and more. You connect clients to these servers, then issue tool calls to perform tasks such as checking balances, uploading IPFS assets, minting licenses, and processing royalties.

How to use

You connect your MCP client to the StoryScan MCP Server and the Story SDK MCP Server. Each server exposes a distinct set of tools. Use the appropriate server for the task you want to perform: blockchain data queries with StoryScan Tools, or IP, licensing, NFT, and revenue operations with Story SDK Tools. When your agent needs to run a tool, prompt it by the tool name or description, and approve the request when prompted.

How to install

Prerequisites you need before starting: Python 3.12 or newer and the UV package manager. Install UV, clone the project repository, install dependencies, then start the servers.

Step-by-step commands you should run:

• Install UV package manager and set up your environment
• Clone the MCP hub and navigate into it
• Install dependencies with UV
• Prepare environment variables for each server
• Run the servers using UV in development mode

# 1) Install UV package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2) Clone the MCP hub and enter directory
git clone https://github.com/piplabs/story-mcp-hub.git
cd story-mcp-hub

# 3) Install dependencies
uv sync

# 4) Set up environment variables for each server
# StoryScan MCP: edit storyscan-mcp/.env accordingly
# Story SDK MCP: edit story-sdk-mcp/.env accordingly

# 5) Start the StoryScan MCP Server
cd storyscan-mcp
uv run mcp dev server.py

# In a separate session, start the Story SDK MCP Server
cd ../story-sdk-mcp
uv run mcp dev server.py

Additional configuration and notes

Each server has its own development setup. StoryScan MCP Server focuses on blockchain data queries and exposes tools for recent transactions, address overviews, token holdings, NFT holdings, statistics, and interpreting transactions. Story SDK MCP Server exposes a broader set of tools for IPFS metadata, license management, IP asset management, NFT collections, revenue and royalties, dispute handling, and WIP token management. When you prepare to run these locally, ensure the environment files for each server are present and correctly configured before starting.

Example startup configuration

The following configuration snippet shows how to configure two local MCP servers that run via the UV runner in stdio mode. You can keep this in a project-specific configuration to connect your MCP clients.

{
  "mcpServers": {
    "storyscan_mcp": {
      "command": "uv",
      "args": ["run", "mcp", "dev", "server.py"]
    },
    "storysdk_mcp": {
      "command": "uv",
      "args": ["run", "mcp", "dev", "server.py"]
    }
  }
}

Available tools

get_transactions

Fetch recent transactions for a given address on the blockchain.

get_stats

Retrieve current blockchain statistics such as total supply, block height, and network metrics.

get_address_overview

Provide a comprehensive overview of an address, including balance, token holdings, and activity.

get_token_holdings

Get all ERC-20 token holdings for an address with balances and token metadata.

get_nft_holdings

Retrieve NFT holdings for an address including collection and token metadata.

interpret_transaction

Return a human-readable interpretation of a blockchain transaction.

upload_image_to_ipfs

Upload an image to IPFS via Pinata and return the IPFS URI.

create_ip_metadata

Create and upload IP metadata for NFTs to IPFS.

get_license_terms

Fetch license terms for a given license ID.

get_license_minting_fee

Get the minting fee for a specific license terms ID.

mint_license_tokens

Mint license tokens for a given IP and license terms and auto-approve WIP tokens.

predict_minting_license_fee

Calculate the minting license fee for provided IP, license terms, and amount.

register

Register an NFT as IP, creating a corresponding IP record.

attach_license_terms

Attach license terms to an IP asset.

mint_and_register_ip_with_terms

Mint and register IP with associated terms.

create_spg_nft_collection

Create an SPG NFT collection for minting and registering IP assets.

get_spg_nft_minting_token

Retrieve the minting fee required by an SPG NFT contract.

pay_royalty_on_behalf

Pay royalties to a receiver IP asset on behalf of a payer IP asset.

claim_all_revenue

Claim all revenue from child IPs of an ancestor IP with optional auto-transfer.

raise_dispute

Raise a dispute against an IP asset with auto-approval of WIP bonds.

deposit_wip

Wrap IP to WIP and deposit to wallet.

transfer_wip

Transfer WIP tokens to a recipient.

get_erc20_token_balance

Get the balance of an ERC20 token for an account.

mint_test_erc20_tokens

Mint test ERC20 tokens if a contract has a public mint/faucet function.