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 addressget_stats: Get current blockchain statisticsget_address_overview: Get a comprehensive overview of an address including balance, token info, and blockchain activityget_token_holdings: Get all ERC-20 token holdings for an address, including detailed token information and balancesget_nft_holdings: Get all NFT holdings for an address, including collection information and individual token metadatainterpret_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 URIcreate_ip_metadata: Create and upload both NFT and IP metadata to IPFS
License Management Tools:
get_license_terms: Retrieve license terms for a specific IDget_license_minting_fee: Get the minting fee for a specific license terms IDget_license_revenue_share: Get the commercial revenue share percentage for a specific license terms IDmint_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 recordattach_license_terms: Attach license terms to an IP assetmint_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 assetsget_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 wallettransfer_wip: Transfer WIP tokens to a recipientget_erc20_token_balance: Get the balance of any ERC20 token for an accountmint_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
- Install UV package manager and install env:
curl -LsSf https://astral.sh/uv/install.sh | sh
- Clone this repository:
git clone https://github.com/piplabs/story-mcp-hub.git
cd story-mcp-hub
- Install dependencies using UV:
uv sync
- 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
- Go to
Cursor Settings>Features>MCP - Click on the
+ Add New MCP Serverbutton - Fill out the form:
- Select the transport under
Type - Enter a nickname for the server in the
Namefield - Enter either the command to run or the URL of the server, depending on the transport
- We'll use the
uvcommand to run the server, so make sure to include the--directoryflag with the path to the server (Example:uv --directory ~/path/to/story-mcp-hub/storyscan-mcp run server.py)
- Select the transport under
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
- Open the Claude Desktop configuration file:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
- 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"
]
}
}
}
- 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:
- Create a new directory for your server
- Implement the MCP protocol in your server
- Add any necessary dependencies to the root
pyproject.toml - 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:
- Install test dependencies:
uv sync --extra test
- Run all tests:
uv run python run_tests.py
- 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
- Run individual test files:
uv run python run_tests.py -t tests/unit/story_sdk_mcp/test_story_service.py
- 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:
- Copy the example file to create your own
.env.test:
cp .env.test.example .env.test
- Edit the
.env.testfile 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:
- Verify that environment variables are set correctly for each server
- Check network connectivity to external APIs (StoryScan, IPFS, etc.)
- Ensure you're using the correct Python version (3.12+)
- Check that all dependencies are installed with
uv sync