Shutter MCP

A Model Context Protocol (MCP) server that provides timelock encryption capabilities using the Shutter Network. This server allows users to encrypt messages that can only be decrypted after a specified future time, enabling trustless time-delayed communications.

Features

• Timelock Encryption: Encrypt messages that unlock at future timestamps
• Natural Language Time Parsing: Use expressions like "3 months from now"
• Unix Timestamp Support: Direct timestamp input for precise timing
• Claude Web, VS Code MCP Support
• Comprehensive Error Handling: User-friendly error messages and guidance
• Production Ready: Docker support, health checks, and monitoring

Important Notice

ALPHA SOFTWARE: This is experimental software using the Shutter Network testnet deployment (Gnosis Chiado). Do not use for production or sensitive data. The encryption implementation is for demonstration purposes only.

Current Limitations:

• Demo encryption algorithm (not production-grade Shutter encryption)
• Testnet deployment (Chiado testnet only)
• No data persistence guarantees
• API may change without notice

Live Deployment

Server URL: https://shutter-mcp-b76e270d48c5.herokuapp.com/ Health Check: https://shutter-mcp-b76e270d48c5.herokuapp.com/health MCP Endpoint: https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp

Quick Start

Claude Web Integration

1. Open Claude Web Settings

   • Visit claude.ai/settings
   • Navigate to "Integrations" section

2. Add Custom Integration

   • Click "Add custom integration"
   • Enter URL: https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp
   • Click "Add"

3. Test the Integration

   • Start a new conversation
   • Try: "Encrypt this message to unlock in 3 months: Hello future!"
   • Or: "Explain how timelock encryption works"

VS Code MCP Integration

1. Install MCP Extension

   • Open VS Code
   • Install the "Model Context Protocol" extension
   • Or install from marketplace: ms-vscode.vscode-mcp

2. Configure MCP Server

   • Open VS Code settings (Ctrl+,)
   • Search for "MCP"
   • Add server configuration:

     {
       "mcp.servers": {
         "shutter-timelock": {
           "url": "https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp",
           "name": "Shutter Timelock Encryption"
         }
       }
     }

3. Test the Integration

   • Open command palette (Ctrl+Shift+P)
   • Type "MCP: Call Tool"
   • Select "timelock_encrypt" and provide parameters

Local Development Setup

If you want to run the server locally for development:

Prerequisites

• Python 3.11 or higher
• pip (Python package manager)

Installation

1. Clone or download this repository

   git clone <your-repo-url>
   cd shutter-mcp-server

2. Run the deployment script

   ./scripts/deploy.sh

3. Start the server

   ./scripts/start.sh

The server will be available at http://localhost:5002 with the MCP endpoint at http://localhost:5002/mcp.

Local Integration Setup

For local development, update your configurations to use:

• Claude Web: http://localhost:5002/mcp
• VS Code: http://localhost:5002/mcp

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# Or build and run manually
docker build -t shutter-mcp-server .
docker run -p 5002:5002 shutter-mcp-server

Testing Examples

Claude Web Test Commands:

Encrypt this message to unlock in 1 hour: Secret meeting at 3pm
Check decryption status for identity: 0x1234...
Explain how timelock encryption works

VS Code Test Commands:

• Use MCP tools through the command palette
• Test timelock encryption with future timestamps
• Verify health endpoint responses

Available Tools

timelock_encrypt(message, unlock_time)

Encrypt a message with timelock encryption using Shutter Network.

Parameters:

• message (string): The text message to encrypt
• unlock_time (string): When the message can be decrypted
  • Natural language: "3 months from now", "1 year from now"
  • Unix timestamp: "1721905313"
  • Absolute date: "2024-12-25", "January 15, 2025"

Example:

timelock_encrypt("Secret auction bid: $50,000", "2024-12-31 23:59:59")

check_decryption_status(identity)

Check if a timelock encrypted message is ready for decryption.

Parameters:

• identity (string): The identity returned from timelock_encrypt

decrypt_timelock_message(identity, encrypted_data)

Decrypt a timelock encrypted message if the timelock has expired.

Parameters:

• identity (string): The identity returned from timelock_encrypt
• encrypted_data (string): The encrypted data returned from timelock_encrypt

get_unix_timestamp(time_expression)

Convert time expressions to Unix timestamps.

Parameters:

• time_expression (string): Time to convert (default: "now")

explain_timelock_encryption()

Get comprehensive explanation of timelock encryption and usage.

How Timelock Encryption Works

Timelock encryption allows you to encrypt a message that can only be decrypted after a specific time. The Shutter Network uses:

• Threshold Cryptography: Distributed key generation and management
• Decentralized Keypers: Network of nodes that collectively manage decryption keys
• Time-based Release: Keys are only released after the specified timestamp
• Trustless Operation: No single party can decrypt messages early

Use Cases

• Sealed Bid Auctions: Hide bids until auction ends
• Time-delayed Announcements: Schedule future reveals
• Dead Man's Switch: Messages that unlock if you don't check in
• Contest Reveals: Hide answers until contest ends
• Future Communications: Send messages to your future self

Configuration

Environment Variables

• PORT: Server port (default: 5002)
• SHUTTER_API_BASE: Shutter API endpoint (default: Chiado testnet)
• SHUTTER_REGISTRY_ADDRESS: Registry contract address

Custom Configuration

Edit src/server.py to modify:

• API endpoints
• Timeout values
• Error handling behavior
• Additional tools

Testing

Run the example script to test functionality:

python examples/usage_example.py

Health check endpoint:

curl https://shutter-mcp-b76e270d48c5.herokuapp.com/health

Local testing:

curl http://localhost:5002/health

Project Structure

shutter-mcp-server/
├── src/
│   └── server.py              # Main server implementation
├── scripts/
│   ├── deploy.sh              # Deployment script
│   └── start.sh               # Start script
├── examples/
│   └── usage_example.py       # Usage examples
├── docs/
│   └── API.md                 # API documentation
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Docker configuration
├── docker-compose.yml         # Docker Compose configuration
├── Procfile                   # Heroku process configuration
├── deploy-heroku.ps1          # PowerShell deployment script
└── README.md                  # This file

Security Considerations

IMPORTANT: This is alpha software with significant limitations:

• Demo Implementation: Current encryption is for demonstration purposes only
• Testnet Only: Uses Chiado testnet - not suitable for production data
• No Production Encryption: Does not implement full Shutter encryption algorithms yet
• Experimental Status: API and functionality may change without notice
• No Data Guarantees: No persistence or availability guarantees

For Production Use:

• Implement proper Shutter encryption algorithms
• Use mainnet deployment when available
• Add authentication and access controls
• Implement proper key management
• Use HTTPS in production deployments

Troubleshooting

Server Won't Start

• Check Python version (3.11+ required)
• Verify all dependencies are installed: pip install -r requirements.txt
• Check port availability: lsof -i :5002 (Linux/Mac) or netstat -an | findstr :5002 (Windows)

Claude Integration Issues

• Ensure server is accessible from the internet
• Verify MCP endpoint returns proper responses: curl https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp
• Check CORS configuration for cross-origin requests

VS Code Integration Issues

• Verify MCP extension is installed and enabled
• Check server configuration in VS Code settings
• Use local server for development: http://localhost:5002/mcp

Shutter API Errors

• Verify internet connectivity
• Check Shutter Network status
• Ensure timestamps are in the future

Development

Adding New Tools

1. Define the tool function with @mcp.tool() decorator
2. Add comprehensive docstring with parameter descriptions
3. Include proper error handling and user guidance
4. Test with the example script

Modifying Time Parsing

Edit the parse_time_expression method in the ShutterTimelock class to support additional time formats.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests and documentation
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Shutter Network for timelock encryption infrastructure
• Model Context Protocol for the integration framework
• FastAPI for the web framework

Support

• Issues: Open a GitHub issue
• Documentation: See docs/ directory
• Examples: Check examples/ directory

---

Version: 2.1.0
Last Updated: August 2025
Compatibility: Claude Web, VS Code MCP, MCP Protocol 2024-11-05