Story Protocol MCP server

The Story Protocol MCP Hub provides a centralized environment for running Model Context Protocol (MCP) servers that enable AI agents to interact with Story Protocol's ecosystem. It includes servers for blockchain data queries and SDK interactions.

Installation

Prerequisites

• Python 3.12 or newer
• UV package manager

Setup Steps

1. Install the UV package manager:

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

2. Clone the repository:

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

3. Install dependencies:

uv sync

4. Configure 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

Starting StoryScan MCP Server

cd storyscan-mcp
uv run mcp dev server.py

Starting Story SDK MCP Server

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

Available MCP Services

StoryScan MCP Server

Provides tools for querying blockchain data:

• check_balance: Check address balances
• get_transactions: Retrieve recent address transactions
• get_stats: Get blockchain statistics
• get_address_overview: Comprehensive address information
• get_token_holdings: View ERC-20 token holdings
• get_nft_holdings: View NFT holdings
• interpret_transaction: Human-readable transaction explanations

Story SDK MCP Server

Provides tools for Story Protocol interactions:

• get_license_terms: Retrieve license terms
• mint_license_tokens: Mint license tokens
• send_ip: Transfer IP tokens
• upload_image_to_ipfs: Upload images to IPFS
• create_ip_metadata: Create NFT metadata
• mint_and_register_ip_with_terms: Register IP with terms

Connecting with MCP Clients

Cursor Integration

1. Go to Cursor Settings > Features > MCP
2. Click + Add New MCP Server
3. Configure the server:
   • Select transport type
   • Enter a server name
   • Enter command or URL
   • Example: uv --directory ~/path/to/story-mcp-hub/storyscan-mcp run server.py

Project-Specific Configuration

Create .cursor/mcp.json with:

{
  "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"
      ]
    }
  }
}

Claude Desktop Integration

1. Edit the Claude Desktop configuration:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Add 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"
      }
    }
  }
}

3. Restart Claude Desktop

Troubleshooting

If you encounter issues:

• Verify environment variables are set correctly
• Check network connectivity to external APIs
• Ensure you're using Python 3.12+
• Verify all dependencies are installed with uv sync

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.