🕰️ OpenTimeStamps MCP Server

A Model Context Protocol (MCP) server that enables AI models to interact with OpenTimeStamps, allowing them to timestamp files and verify proofs on the Bitcoin blockchain.

Trustless timestamping for the AI age.

🚀 Features

• 🔢 Calculate hash values (SHA256, SHA1, RIPEMD160)
• ⏰ Submit hashes for timestamping via OpenTimeStamps calendars
• 📁 Load and parse OTS proof files
• 📊 Display detailed information about OTS proofs
• ⬆️ Upgrade incomplete OTS proofs
• ✅ Verify OTS proofs against original data or hashes
• 🌐 Server-Sent Events (SSE) support for web integration
• 🔌 MCP-compliant API for AI integration

📋 Prerequisites

• Node.js 18+

🛠️ Installation

Installing via Smithery (Coming Soon)

To install OpenTimeStamps MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @fmar/opentimestamps-mcp --client claude

Manual Installation

1. Clone the repository:

git clone https://github.com/fmargarita/opentimestamps-mcp
cd opentimestamps-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Create a .env file (optional):

You can copy .env.example and modify as needed:

cp .env.example .env

🔧 Setup with Claude Desktop

To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration file:

macOS

# Edit the configuration file
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

# Edit the configuration file
notepad %APPDATA%\Claude\claude_desktop_config.json

Configuration

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "opentimestamps": {
      "command": "node",
      "args": ["/absolute/path/to/opentimestamps-mcp/build/cli.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Important: Replace /absolute/path/to/opentimestamps-mcp/ with the actual path where you cloned this repository.

After updating the configuration:

1. Restart Claude Desktop
2. You should see the OpenTimeStamps tools available in your conversation

🔧 Setup with Goose

For Goose AI assistant, add this to your config.yaml:

mcp:
  servers:
    opentimestamps:
      command: node
      args:
        - /absolute/path/to/opentimestamps-mcp/build/cli.js
      env:
        LOG_LEVEL: info

🚦 Usage

Starting the Server

# Development mode with hot reload
npm run dev

# Production mode
npm start

Available Tools

calculate_hash

Calculate the hash of data using the specified algorithm.

Example input:

{
  "data": "Hello, OpenTimeStamps!",
  "algorithm": "sha256"
}

stamp_hash

Submit a hash for timestamping using OpenTimeStamps calendar servers.

Example input:

{
  "hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "algorithm": "sha256"
}

load_proof

Load an OTS proof from hex data or file path.

Example input:

{
  "otsData": "004f70656e54696d657374616d7073000050726f6f66...",
  "isFilePath": false
}

get_proof_info

Display detailed information about an OTS proof.

Example input:

{
  "otsData": "004f70656e54696d657374616d7073000050726f6f66..."
}

upgrade_proof

Upgrade an incomplete OTS proof by fetching missing attestations.

Example input:

{
  "otsData": "004f70656e54696d657374616d7073000050726f6f66..."
}

verify_proof

Verify an OTS proof against original data or hash.

Example input:

{
  "otsData": "004f70656e54696d657374616d7073000050726f6f66...",
  "originalData": "Hello, OpenTimeStamps!",
  "algorithm": "sha256"
}

🔧 Development

Project Structure

opentimestamps-mcp/
├── src/
│   ├── index.ts        # Main server entry point
│   ├── ots-client.ts   # OpenTimeStamps client implementation
│   ├── stdio_server.ts # STDIO transport server
│   ├── sse_server.ts   # SSE transport server
│   ├── types.ts        # TypeScript type definitions
│   ├── types/          # Type declarations
│   └── utils/          # Utility functions
├── .env.example        # Environment configuration template
├── claude_desktop_config.json # Claude Desktop config example
└── tsconfig.json       # TypeScript configuration

Running Tests

npm test

📚 Examples

Basic Workflow

1. Calculate a hash of your data:

   Use the calculate_hash tool with your text or data
   

2. Submit for timestamping:

   Use the stamp_hash tool with the resulting hash
   

3. Check the proof:

   Use get_proof_info to see the attestation details
   

4. Upgrade proof (after ~10 minutes):

   Use upgrade_proof to get Bitcoin confirmations
   

5. Verify the proof:

   Use verify_proof with your original data and the proof
   

Sample Conversation with Claude

User: "Please calculate the SHA256 hash of 'Hello World'"

Claude will use: calculate_hash
Input: {"data": "Hello World", "algorithm": "sha256"}

User: "Now timestamp that hash"

Claude will use: stamp_hash  
Input: {"hash": "a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e", "algorithm": "sha256"}

User: "Show me the proof information"

Claude will use: get_proof_info
Input: {"otsData": "004f70656e54696d657..."}

🔒 Privacy & Security

OpenTimeStamps provides cryptographic proof of existence without revealing file contents:

• Privacy: Only file hashes are submitted to calendar servers, never the actual data
• Trustless: Verification is done against the Bitcoin blockchain, not trusted third parties
• Immutable: Once timestamped on Bitcoin, proofs cannot be altered or removed
• Verifiable: Anyone can independently verify timestamps using the Bitcoin blockchain

⚙️ Configuration

All configuration is optional and handled through environment variables:

• OTS_CALENDAR_SERVERS: Custom calendar servers (defaults to standard OTS servers)
• BITCOIN_RPC_*: Bitcoin node connection for local verification (optional)
• SERVER_MODE: Choose between stdio (default) or sse transport
• PORT: HTTP port for SSE mode (default: 3000)

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Resources

• OpenTimeStamps Website
• OpenTimeStamps Python Client
• OpenTimeStamps JavaScript Library
• Model Context Protocol
• Visual testing tool for MCP servers
• Awesome MCP Servers

🚀 Getting Started

The fastest way to test the server:

1. Calculate a hash:

   "Calculate the SHA256 hash of 'Hello World'"
   

2. Timestamp the hash:

   "Timestamp that hash using OpenTimeStamps"
   

3. Verify later:

   "Verify the proof against the original text 'Hello World'"
   

---

<p align="center"> Made with ❤️ for timestamping and blockchain verification </p>