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

Open Claude Web Settings
- Visit claude.ai/settings
- Navigate to "Integrations" section
Add Custom Integration
- Click "Add custom integration"
- Enter URL: https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp
- Click "Add"
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

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

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

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

Clone or download this repository

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

Run the deployment script
```
./scripts/deploy.sh
```
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

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

Modifying Time Parsing

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

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests and documentation
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

Shutter MCP

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

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

Quick Start

Claude Web Integration

Open Claude Web Settings
- Visit claude.ai/settings
- Navigate to "Integrations" section
Add Custom Integration
- Click "Add custom integration"
- Enter URL: https://shutter-mcp-b76e270d48c5.herokuapp.com/mcp
- Click "Add"
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

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

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

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

Clone or download this repository

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

Run the deployment script
```
./scripts/deploy.sh
```
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

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

Modifying Time Parsing

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

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests and documentation
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