Skip to main content
Glama

Story SDK MCP Server

by piplabs

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

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
  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
    • We'll use the uv command to run the server, so make sure to include the --directory flag with the path to the server (Example: uv --directory ~/path/to/story-mcp-hub/storyscan-mcp run server.py)

Screenshot 2025-03-10 at 2 50 48 PM

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 that are listed under Available Tools on the MCP settings page if it determines them to be relevant. To prompt tool usage intentionally, simply tell the agent to use the tool, referring to it either by name or by 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" ] }, "story-sdk-mcp": { "command": "uv", "args": [ "--directory", "~/path/to/story-mcp-hub/story-sdk-mcp", "run", "server.py" ] } } }
  1. Save the file and restart Claude Desktop for the changes to take effect.

Screenshot 2025-03-10 at 2 57 24 PM

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 any necessary dependencies to the root pyproject.toml
  4. Update this README with information about your server

Testing

Running Tests

The project includes a test runner script (run_tests.py) that handles environment setup and test execution. To run tests:

  1. Install test dependencies:
uv sync --extra test
  1. Run all tests:
uv run python run_tests.py
  1. Run specific test categories:
# Run unit tests only uv run python run_tests.py -t tests/unit/ # Run integration tests only uv run python run_tests.py -t tests/integration/ # Run with verbose output uv run python run_tests.py -v
  1. Run individual test files:
uv run python run_tests.py -t tests/unit/story_sdk_mcp/test_story_service.py
  1. Get help on available options:
uv run python run_tests.py --help

Environment Setup for Testing

The tests use a .env.test file with mock credentials for testing. This file is automatically loaded by the test runner.

To set up your test environment:

  1. Copy the example file to create your own .env.test:
cp .env.test.example .env.test
  1. Edit the .env.test file to include your test credentials:
# For example, update the private key for blockchain interactions nano .env.test # or use your preferred text editor

For more detailed information about testing, see the testing guide.

Troubleshooting

If you encounter issues:

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

License

MIT License

-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Provides tools for managing IP assets and licenses, interacting with the Story Python SDK, and handling operations like minting tokens, registering IP, and uploading metadata to IPFS.

  1. Project Structure
    1. MCP Servers
      1. StoryScan MCP Server
      2. Story SDK MCP Server
    2. Setup
      1. Prerequisites
      2. Installation
    3. Running the Servers
      1. StoryScan MCP Server Inspector
      2. Story SDK MCP Server
    4. Using with MCP Clients
      1. Cursor
      2. Claude Desktop
    5. Development
      1. Troubleshooting
        1. License

          Related MCP Servers

          • A
            security
            A
            license
            A
            quality
            A Model Context Protocol server that provides tools for Xcode-related operations, making it easier to work with iOS project management, building, testing, archiving, and deploying apps to both simulators and physical devices.
            Last updated -
            9
            49
            6
            MIT License
            • Apple
          • A
            security
            A
            license
            A
            quality
            A Model Context Protocol server that integrates with Storybook to help AI tools query UI components and retrieve usage examples from static Storybook files.
            Last updated -
            2
            51
            17
            MIT License
          • A
            security
            A
            license
            A
            quality
            Provides tools for creating, managing, and generating content for DeepWriter projects through a standardized Model Context Protocol interface.
            Last updated -
            6
            6
            Apache 2.0
            • Apple
          • A
            security
            A
            license
            A
            quality
            The Storyblok MCP server enables your AI assistants to directly access and manage your Storyblok spaces, stories, components, assets, workflows, and more.
            Last updated -
            25
            Python
            MIT License

          View all related MCP servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/piplabs/story-mcp-hub'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server