Shuttermcp

🚀 Shutter MCP

A Model Context Protocol (MCP) server that provides timelock encryption capabilities using the Shutter Network. It enables trustless time-delayed communications by allowing users to encrypt messages decryptable only after a specified future time.

🚀 Quick Start

Claude Web Integration

1. Open Claude Web Settings:
   • Visit claude.ai/settings.
   • Navigate to the "Integrations" section.
2. Add Custom Integration:
   • Click "Add custom integration".
   • Enter the URL: https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp.
   • Click "Add".
3. Test the Integration:
   • Start a new conversation.
   • Try commands like "Encrypt this message to unlock in 3 months: Hello future!" or "Explain how timelock encryption works".

VS Code MCP Integration

1. Install the MCP Extension:
   • Open VS Code.
   • Install the "Model Context Protocol" extension or install it from the marketplace: ms-vscode.vscode-mcp.
2. Configure the MCP Server:
   • Open VS Code settings (Ctrl+,).
   • Search for "MCP".
   • Add the following server configuration:

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

3. Test the Integration:
   • Open the command palette (Ctrl+Shift+P).
   • Type "MCP: Call Tool".
   • Select "timelock_encrypt" and provide the required parameters.

✨ 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: Seamless integration with these platforms.
• Comprehensive Error Handling: User - friendly error messages and guidance.
• Production Ready: Docker support, health checks, and monitoring.

⚠️ Important Note

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

📦 Installation

Local Development Setup

Prerequisites

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

Steps

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

💻 Usage 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.

📚 Documentation

Available Tools

timelock_encrypt(message, unlock_time)

Encrypt a message with timelock encryption using the Shutter Network.

• Parameters:
  • message (string): The text message to encrypt.
  • unlock_time (string): When the message can be decrypted. Can be in natural language (e.g., "3 months from now"), Unix timestamp (e.g., "1721905313"), or absolute date (e.g., "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 a comprehensive explanation of timelock encryption and its 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: A 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 the 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 the 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 the 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 the server is accessible from the internet.
• Verify the 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 the MCP extension is installed and enabled.
• Check the server configuration in VS Code settings.
• Use the local server for development: http://localhost:5002/mcp.

Shutter API Errors

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

Development

Adding New Tools

1. Define the tool function with the @mcp.tool() decorator.
2. Add a 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

This project is under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

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

🛠️ Support

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

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