Story MCP Hub

This repository serves as a central hub for Story Protocol's Model Context Protocol (MCP) servers. It provides a unified environment for running and managing various MCP services that enable AI agents to interact with Story Protocol's ecosystem.

Project Structure

story-mcp-hub/
├── storyscan-mcp/       # MCP server for blockchain data queries via StoryScan
├── story-sdk-mcp/       # MCP server for Story Protocol SDK interactions
├── utils/               # Shared utilities for MCP servers
├── .venv/               # Python virtual environment
├── pyproject.toml       # Project dependencies and configuration
├── .python-version      # Python version specification
└── README.md            # This file

graph TD
    subgraph "MCP Hub"
        style MCP Hub fill:#F5F5FF,stroke:#9999CC,stroke-width:2px,rx:10,ry:10
        Agent["AI Agent<br>(Claude, IDEs, Tools)"]
        style Agent fill:#E6E6FA,stroke:#9370DB,stroke-width:2px,rx:8,ry:8
    end
subgraph "StoryScan MCP Server"

        style StoryScan MCP Server fill:#F0F8FF,stroke:#87CEFA,stroke-width:2px,rx:10,ry:10

        StoryscanService["StoryScan Service"]

        style StoryscanService fill:#E6E6FA,stroke:#9370DB,stroke-width:2px,rx:8,ry:8
subgraph "StoryScan Tools"

            style StoryScan Tools fill:#F0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:10,ry:10

            StoryscanToolset["Blockchain Data<br>get_transactions,<br>get_address_overview,<br>get_token_holdings,<br>get_nft_holdings,<br>get_stats,<br>interpret_transaction"]

            style StoryscanToolset fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8

        end

    end
subgraph "Story SDK MCP Server"

        style Story SDK MCP Server fill:#F5FFFA,stroke:#98FB98,stroke-width:2px,rx:10,ry:10

        StoryService["Story Service"]

        style StoryService fill:#E6E6FA,stroke:#9370DB,stroke-width:2px,rx:8,ry:8
subgraph "Story SDK Tools"

            style Story SDK Tools fill:#F0FFF0,stroke:#90EE90,stroke-width:2px,rx:10,ry:10

            IPFSTools["IPFS & Metadata<br>upload_image_to_ipfs<br>create_ip_metadata"]

            style IPFSTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8

            LicenseTools["License Management<br>get_license_terms,<br>mint_license_tokens,<br>get_license_minting_fee,<br>predict_minting_license_fee"]

            style LicenseTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8

            IPTools["IP & NFT Management<br>register, attach_license_terms,<br>mint_and_register_ip_with_terms,<br>create_spg_nft_collection"]

            style IPTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8

            TokenTools["Token & Revenue<br>deposit_wip, transfer_wip,<br>pay_royalty_on_behalf,<br>claim_all_revenue,<br>raise_dispute"]

            style TokenTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8

        end

    end
subgraph "External Resources"

        style External Resources fill:#FFF0F5,stroke:#FFB6C1,stroke-width:2px,rx:10,ry:10

        IPFS[(IPFS/Pinata<br>Storage)]

        style IPFS fill:#FFE4E1,stroke:#DB7093,stroke-width:2px,rx:15,ry:15

        Blockchain[(Story Protocol<br>Blockchain)]

        style Blockchain fill:#E0F8E0,stroke:#90EE90,stroke-width:2px,rx:15,ry:15

        StoryScan[(StoryScan/Blockscout<br>API)]

        style StoryScan fill:#E6F3FF,stroke:#87CEFA,stroke-width:2px,rx:15,ry:15

    end
Agent <--MCP Protocol--> StoryService

    Agent <--MCP Protocol--> StoryscanService

    StoryscanService --> StoryscanToolset

    StoryService --> IPFSTools

    StoryService --> LicenseTools

    StoryService --> IPTools

    StoryService --> TokenTools
StoryscanToolset <--API Calls--> StoryScan

    IPFSTools <--API Calls--> IPFS

    LicenseTools <--RPC Calls--> Blockchain

    IPTools <--RPC Calls--> Blockchain

    TokenTools <--RPC Calls--> Blockchain

MCP Servers

StoryScan MCP Server

Provides tools for querying blockchain data, including address balances, transactions, and blockchain statistics.

Tools:

- get_transactions: Get recent transactions for an address
- get_stats: Get current blockchain statistics
- get_address_overview: Get a comprehensive overview of an address including balance, token info, and blockchain activity
- get_token_holdings: Get all ERC-20 token holdings for an address, including detailed token information and balances
- get_nft_holdings: Get all NFT holdings for an address, including collection information and individual token metadata
- interpret_transaction: Get a human-readable interpretation of a blockchain transaction

Story SDK MCP Server

Provides tools for interacting with Story Protocol's Python SDK.

Tools:

IPFS & Metadata Tools (requires PINATA_JWT):
- upload_image_to_ipfs: Upload an image to IPFS using Pinata API and return the URI
- create_ip_metadata: Create and upload both NFT and IP metadata to IPFS

License Management Tools:
- get_license_terms: Retrieve license terms for a specific ID
- get_license_minting_fee: Get the minting fee for a specific license terms ID
- get_license_revenue_share: Get the commercial revenue share percentage for a specific license terms ID
- mint_license_tokens: Mint license tokens for a given IP and license terms (auto-approves WIP tokens)
- predict_minting_license_fee: Pre-compute the minting license fee for given IP, license terms and amount

IP Asset Management Tools:
- 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 an IP with terms

NFT Collection Tools:
- create_spg_nft_collection: Create a new SPG NFT collection that can be used for minting and registering IP assets
- get_spg_nft_minting_token: Get the minting fee required by an SPG NFT contract

Revenue & Royalty Tools:
- pay_royalty_on_behalf: Pay royalties to a receiver IP asset on behalf of a payer IP asset (auto-approves tokens)
- claim_all_revenue: Claim all revenue from child IPs of an ancestor IP with optional auto-transfer

Dispute Tools:
- raise_dispute: Raise a dispute against an IP asset (auto-approves WIP bond tokens)

Token Management Tools:
- 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 any ERC20 token for an account
- mint_test_erc20_tokens: Mint test ERC20 tokens if the contract has a public mint/faucet function

Setup

Prerequisites

- Python 3.12+
- UV package manager

Installation

1. Install UV package manager and install env:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone this repository:

git clone https://github.com/piplabs/story-mcp-hub.git
cd story-mcp-hub

3. Install dependencies using UV:

uv sync

4. Set up environment variables for each server:

For StoryScan MCP:

```bash
cd storyscan-mcp
cp .env.example .env