Shape MCP Server

Model Context Protocol (MCP) server for Shape, built with xmcp. This server provides AI assistants access to Shape's onchain data: gasback distribution, collections analytics, stack users & more.

Contributions are welcome! Fork and add your own tools, feel free to submit a PR.

Check our docs about how to build AI on Shape: https://docs.shape.network/building-on-shape/ai

Features

Organized by functionality for easy extension:

• Gasback Analytics - Track creator earnings, top performers, and simulate gasback earned
• NFT Analysis - Collections and ownership
• Stack Achievements - Monitor user progress in Shape's Stack ecosystem
• Network Monitoring - Chain health, metrics, RPC URLs, etc
• AI Ready - Tools are optimized for agent chaining and automation
• Caching - Optional Redis for snappier responses & less load on RPCs, no lock-in required

Available Tools

Network Tools (/tools/network/)

getChainStatus

Monitor Shape's network: RPC health, gas prices, block times, etc.

Example prompt: "current shape status? gas prices looking mint-friendly?"

NFT Tools (/tools/nft/)

getCollectionAnalytics

Collection stats: supply, owners, sample NFTs, floors, etc.

Example prompt: "what's the vibe on collection 0x567...abc? floor price and top holders?"

getShapeNft

List NFTs for an address, with metadata.

Example prompt: "what NFTs does 0xabcd...123 hold on shape?"

Gasback Tools (/tools/gasback/)

getShapeCreatorAnalytics

Shape builder/creator deep dive: earnings, tokens, withdrawals, etc.

Example prompt: "analyze creator 0xabcd...123's gasback and compare to top earners. any tips?"

getTopShapeCreators

Top creators by gasback earned & tx.

Example prompt: "who are shape's top 10 gasback earners?"

simulateGasbackRewards

Get gasback rough estimates.

Example prompt: "simulate 50 txs/day at 50k gas—earnings over 3 months? wen lambo?"

🏗️ Stack Tools (/tools/stack/)

getStackAchievements

User medals by tier, total count, etc.

Example prompt: "what's 0xghi...123's stack status? gold medals?"

Quick Test (No Setup Required)

Want to try the MCP server without local setup? Point directly to our deployed instance:

{
"mcpServers": {
"shape-mcp": {
"url": "https://shape-mcp-server.vercel.app/mcp"
}
}
}

Note: This deployed version is rate limited and is intended for testing/sandbox use only. For production AI applications, we recommend self-hosting your own instance following the setup instructions above.

Prerequisites

• Alchemy API key for NFT queries (get one here)
• MCP client like Cursor IDE, Claude Desktop or your AI client of choice
• Optional: Redis for caching (speeds up RPC-heavy tools)

Setup

1. Environment Configuration

Copy .env.example to .env and fill in:

ALCHEMY_API_KEY=your_key_here
CHAIN_ID=360 # Mainnet; use 11011 for Sepolia# Optional caching
REDIS_URL=redis://localhost:6379 # Local, or Upstash for prod

2. Install Dependencies

yarn install

3. Run Locally

yarn dev

Server is now running at http://localhost:3002/mcp

🔌 Client Integration

MCP Settings

Add to your MCP settings in Cursor for eg:

{
"mcpServers": {
"shape-mcp": {
"url": "http://localhost:3002/mcp"
}
}
}

Project Structure

src/
├── tools/ # Modular tools
│ ├── gasback/
│ ├── network/
│ ├── nft/
│ └── stack/
├── abi/ # Contract interfaces
├── utils/ # Helpers like cache.ts
├── addresses.ts # Key contracts addys
├── clients.ts # RPC/Alchemy/Redis
├── config.ts # Env-based setup
├── middleware.ts # Auth/logging if needed
├── types.ts # Shared outputs
└── xmcp.config.ts # xmcp server config

Categories keep things modular. Add a tool to /tools/gasback/ and xmcp auto-picks it up. No monolith mess.

Adding New Tools

1. Pick a category folder (e.g., /tools/gasback/)
2. New .ts file with schema, metadata, function
3. Example:

import{z}from'zod';import{typeInferSchema}from'xmcp';exportconstschema={address: z.string().describe('Wallet to analyze'),};exportconstmetadata={name: 'myTool',description: 'Custom tool for fun insights',annotations: {title: 'My Tool',readOnlyHint: true,destructiveHint: false,idempotentHint: true,requiresWallet: false,category: 'gasback',chainableWith: ['getShapeCreatorAnalytics'],},};exportdefaultasyncfunctionmyTool({ address }: InferSchema<typeofschema>){// Logic herereturn{content: [{type: 'text',text: JSON.stringify(result,null,2)}],};}

Caching (Optional)

Redis cuts RPC load for repeat calls. Set REDIS_URL to your instance (Vercel KV or Upstash). Skip it? Tools run direct, no sweat. See cache.ts for the simple get/set logic.

Deploy Your Own

Fork this repo and deploy your personal MCP:

1. Fork on GitHub
2. Import to Vercel: New Project
3. Set env vars: SHAPE_RPC_URL (your node), ALCHEMY_API_KEY, CHAIN_ID (360 for mainnet, or 11011 for testnet), optional REDIS_URL
4. Deploy—access at your-vercel-url/mcp!

RPC Setup

Use your own Alchemy API key to avoid public RPC limits. Default falls back to Shape’s public node https://mainnet.shape.network and https://sepolia.shape.network.

Resources

• Shape Docs
• xmcp Framework
• Alchemy Docs

Support

Contact @williamhzo or hop into Shape Discord.

---

MIT LICENSE - See LICENSE