MCP HubMCP Hub
piplabs

story-mcp-hub

by: piplabs

An MCP server for the Story SDK and Storyscan Block Explorer

11created 24/02/2025
Visit
SDK
Blockchain

📌Overview

Purpose: The Story MCP Hub serves as a centralized platform for managing and running various Model Context Protocol (MCP) servers for enhancing AI interactions within the Story Protocol ecosystem.

Overview: This repository provides essential tools and services for both blockchain data queries and interactions with the Story Protocol SDK. By consolidating multiple MCP servers, it allows developers to effectively integrate AI agents with the Story Protocol's functionalities.

Key Features:

  • StoryScan MCP Server: Offers a suite of tools for querying blockchain data, including checking balances, retrieving transaction histories, and summarizing address statistics to help users engage with blockchain information seamlessly.

  • Story SDK MCP Server: Facilitates interaction with Story Protocol's SDK, enabling actions such as uploading images to IPFS, minting license tokens, and managing intellectual property, thus streamlining API interactions for developers.

Story MCP Hub

This repository serves as a central hub for Story Protocol's Model Context Protocol (MCP) servers, providing 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

MCP Servers

StoryScan MCP Server

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

Tools:

  • check_balance: Check the balance of an address
  • get_transactions: Get recent transactions for an address
  • get_stats: Get current blockchain statistics
  • get_address_overview: Get a comprehensive overview of an address
  • get_token_holdings: Get all ERC-20 token holdings for an address
  • get_nft_holdings: Get all NFT holdings for an address
  • interpret_transaction: Get a human-readable interpretation of a transaction

Story SDK MCP Server

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

Tools:

  • get_license_terms: Retrieve license terms for a specific ID
  • mint_license_tokens: Mint license tokens for a specific IP and license terms
  • send_ip: Send IP tokens to a specified address using native token transfer
  • upload_image_to_ipfs: Upload an image to IPFS and return the URI
  • create_ip_metadata: Create NFT metadata for a specific image URI
  • mint_and_register_ip_with_terms: Mint and register an IP with terms

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
  1. Clone this repository:
git clone https://github.com/piplabs/story-mcp-hub.git
cd story-mcp-hub
  1. Install dependencies using UV:
uv sync
  1. Set up environment variables for each server:

For StoryScan MCP:

cd storyscan-mcp
cp .env.example .env
# Edit .env with your StoryScan API endpoint

For Story SDK MCP:

cd story-sdk-mcp
cp .env.example .env
# Edit .env with your wallet private key, RPC provider URL, etc.

Running the Servers

StoryScan MCP Server Inspector

cd storyscan-mcp
uv run mcp dev server.py

Story SDK MCP Server

cd story-sdk-mcp
uv run mcp dev server.py

Using with MCP Clients

Follow the instructions below to connect the MCP servers to various MCP-compatible clients.

Cursor

Cursor implements an MCP client that supports an arbitrary number of MCP servers with both stdio and sse transports.

Adding MCP Servers in Cursor

  1. Go to Cursor Settings > Features > MCP
  2. Click on the + Add New MCP Server button
  3. Fill out the form:
    • Select the transport under Type
    • Enter a nickname for the server in the Name field
    • Enter either the command to run or the URL of the server, depending on the transport
      Use the uv command to run the server, including the --directory flag with the path to the server (Example: uv --directory ~/path/to/story-mcp-hub/storyscan-mcp run server.py)

Project-Specific MCP Configuration

You can configure project-specific MCP servers using .cursor/mcp.json. The file follows this format:

{
  "mcpServers": {
    "storyscan-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "~/path/to/story-mcp-hub/storyscan-mcp",
        "run",
        "server.py"
      ]
    },
    "story-sdk-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "~/path/to/story-mcp-hub/story-sdk-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

Using MCP Tools in Cursor

The Composer Agent will automatically use any MCP tools listed under Available Tools on the MCP settings page if it determines them relevant. To prompt tool usage intentionally, simply tell the agent to use the tool, referring to it either by name or description.

When the Agent wants to use an MCP tool, it will display a message asking for your approval.

Claude Desktop

Claude Desktop can be configured to use MCP servers by editing its configuration file.

Adding MCP Servers in Claude Desktop

  1. Open the Claude Desktop configuration file:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
  1. Add the MCP server configuration:
{
  "mcpServers": {
    "storyscan-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "~/path/to/story-mcp-hub/storyscan-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "STORY_API_KEY": "your_story_api_key_here",
        "STORYSCAN_API_ENDPOINT": "your_story_api_endpoint_here"
      }
    },
    "story-sdk-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "~/path/to/story-mcp-hub/story-sdk-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "WALLET_PRIVATE_KEY": "your_private_key_here",
        "RPC_PROVIDER_URL": "your_rpc_provider_url_here",
        "PINATA_JWT": "your_pinata_jwt_here"
      }
    }
  }
}
  1. Save the file and restart Claude Desktop for the changes to take effect.

Example query: use storyscan to check balance of 0x95A13F457C76d10A40D7e8497eD4F40c53F4d04b

Development

To add a new MCP server to the hub:

  1. Create a new directory for your server
  2. Implement the MCP protocol in your server
  3. Add necessary dependencies to the root pyproject.toml
  4. Update this README with information about your server

Troubleshooting

If you encounter issues:

  1. Verify environment variables are set correctly for each server
  2. Check network connectivity to external APIs (StoryScan, IPFS, etc.)
  3. Ensure you are using Python 3.12+
  4. Verify that all dependencies are installed with uv sync

License

MIT License