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

Related MCP server: Vaulted MCP Server

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