🕰️ 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.

![TypeScript](https://www.typescriptlang.org/) ![MCP](https://github.com/modelcontextprotocol/typescript-sdk) ![OpenTimeStamps](https://opentimestamps.org/)

🚀 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

Clone the repository:

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

Install dependencies:

npm install

Build the project:

npm run build

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:

Restart Claude Desktop
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

Calculate a hash of your data:

   Use the calculate_hash tool with your text or data

Submit for timestamping:

   Use the stamp_hash tool with the resulting hash

Check the proof:

   Use get_proof_info to see the attestation details

Upgrade proof (after ~10 minutes):

   Use upgrade_proof to get Bitcoin confirmations

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

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

📜 License

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

🔗 Resources

🚀 Getting Started

The fastest way to test the server:

Calculate a hash:

   "Calculate the SHA256 hash of 'Hello World'"

Timestamp the hash:

   "Timestamp that hash using OpenTimeStamps"

Verify later:

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

---

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

OpenTimeStamps MCP Server