Stampchain MCP Server

A Model Context Protocol (MCP) server for interacting with Bitcoin Stamps and SRC-20 token data via the Stampchain API. This server provides MCP-compatible clients with tools to query Bitcoin Stamps, collections, and SRC-20 tokens.

Features

Bitcoin Stamps Tools: Get stamp details, search stamps, and retrieve recent stamps
Stamp Collections: Query collections and search through collection data
SRC-20 Tokens: Get token information and search through SRC-20 tokens
Type-safe: Built with TypeScript and Zod validation
Comprehensive Testing: Full test coverage with CI validation
Configurable: Flexible configuration options for different environments
Cross-platform: Works on Ubuntu, Windows, and macOS with Node.js 18+

Quick Start

Prerequisites

Node.js 18+
npm or yarn

Installation

Clone the repository:
git clone https://github.com/stampchain-io/stampchain-mcp.git cd stampchain-mcp
Install dependencies:
npm install
Build the project:
npm run build
Test the installation:
npm run start

MCP Client Integration

Claude Desktop

To use with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "stampchain": {
      "command": "node",
      "args": ["/path/to/stampchain-mcp/dist/index.js"],
      "cwd": "/path/to/stampchain-mcp"
    }
  }
}

Alternative: Using npx (recommended)

For easier setup without local installation:

{
  "mcpServers": {
    "stampchain": {
      "command": "npx",
      "args": ["-y", "stampchain-mcp"]
    }
  }
}

Note: Replace /path/to/stampchain-mcp with the actual path to your installation directory.

Other MCP Clients

This server implements the standard MCP protocol and can be used with any MCP-compatible client. Refer to your client's documentation for specific configuration instructions. The server accepts connections via stdio transport.

Available Tools

Bitcoin Stamps

get_stamp - Get detailed information about a specific stamp by ID
search_stamps - Search stamps with various filters (creator, collection, etc.)
get_recent_stamps - Get the most recently created stamps

Stamp Collections

get_collection - Get detailed information about a specific collection
search_collections - Search collections with filters

SRC-20 Tokens

get_token_info - Get detailed information about a specific SRC-20 token
search_tokens - Search SRC-20 tokens with various filters

Configuration

The server can be configured through:

Configuration file (JSON format)
Environment variables
Command line arguments

Example Configuration File

{
  "api": {
    "baseUrl": "https://stampchain.io/api",
    "timeout": 30000,
    "retries": 3
  },
  "logging": {
    "level": "info"
  },
  "registry": {
    "maxTools": 1000,
    "validateOnRegister": true
  }
}

Environment Variables

STAMPCHAIN_API_URL - API base URL (default: https://stampchain.io/api)
STAMPCHAIN_LOG_LEVEL - Logging level (debug, info, warn, error)
STAMPCHAIN_API_TIMEOUT - API timeout in milliseconds

Command Line Usage

# Start with default configuration
npm run start

# Start with custom config file
npm run start -- --config config.json

# Start with debug logging
npm run start -- --log-level debug

# Show available tools
npm run tools

# Show version information
npm run version

Development

Scripts

npm run dev - Start development server with hot reload
npm run build - Build the TypeScript project
npm run test - Run all tests
npm run test:watch - Run tests in watch mode
npm run test:coverage - Run tests with coverage report
npm run typecheck - TypeScript type checking
npm run format - Format code with Prettier
npm run validate - Full validation suite

Testing

The project includes comprehensive test coverage:

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode during development
npm run test:watch

Project Structure

src/
├── api/           # API client and related utilities
├── config/        # Configuration management
├── interfaces/    # TypeScript interfaces
├── protocol/      # MCP protocol handlers
├── schemas/       # Zod validation schemas
├── tools/         # MCP tool implementations
├── utils/         # Utility functions
├── index.ts       # Main entry point
└── server.ts      # Server implementation

API Reference

Tool Parameters

All tools accept various parameters for filtering and pagination:

limit - Number of results to return (default: 10, max: 100)
page - Page number for pagination (default: 1)
sort - Sort field and direction (e.g., "created_desc")

Response Format

All tools return structured data with:

success - Boolean indicating if the request was successful
data - The requested data (stamps, collections, tokens)
pagination - Pagination information when applicable
error - Error details if the request failed

Troubleshooting

Common Issues

Build Errors: Ensure you have Node.js 18+ and run npm install first
Connection Issues: Check that the Stampchain API is accessible
MCP Client Integration: Verify the path in your configuration file is correct

Debugging

Enable debug logging to see detailed information:

npm run start -- --debug

Or set the log level in your configuration:

{
  "logging": {
    "level": "debug"
  }
}

Development

Test Coverage

This project maintains comprehensive test coverage across multiple areas:

✅ Unit Tests - Core utilities and helper functions
✅ Integration Tests - MCP server functionality
✅ API Validation - Ensures v2.3 API compatibility
✅ Schema Validation - TypeScript and Zod schema alignment
✅ Cross-platform - Tested on Ubuntu, Windows, and macOS
✅ Multi-version - Node.js 18.x, 20.x, and 22.x support
✅ Real API Testing - Validates against live Stampchain API v2.3

Detailed Testing Commands

# Run specific test suites
npm run test:unit         # Unit tests for utilities and helpers
npm run test:integration  # Integration tests for MCP server
npm run test:api         # API validation tests (v2.3 compatibility)
npm run test:tools       # Tool functionality tests
npm run test:schemas     # Schema validation tests

# Advanced testing options
npm run test:ui          # Run tests in UI mode (interactive)
npm run test:ci          # CI test run (includes coverage)
npm run validate         # Full validation (schema + typecheck + format + tests)

Development Workflow

Install dependencies: npm install
Start development server: npm run dev
Run tests in watch mode: npm run test:watch
Validate before commit: npm run validate

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/new-feature
Make your changes
Run tests: npm test
Commit your changes: git commit -am 'Add new feature'
Push to the branch: git push origin feature/new-feature
Submit a pull request

Code Style

Use TypeScript for all new code
Follow TypeScript strict mode guidelines
Write tests for new features
Update documentation as needed
Run npm run validate before submitting PRs

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Documentation: Stampchain API Docs
Community: Telegram @BitcoinStamps

Changelog

v0.2.0

Stampchain API v2.3 Compatibility: Updated schemas and validation for latest API
Enhanced Testing: Comprehensive test suite with cross-platform CI validation
Improved Documentation: Professional README with status badges and better organization
Simplified Development: Streamlined validation pipeline (TypeScript + Prettier)
Bug Fixes: Resolved CI issues and schema validation improvements

v0.1.0

Initial release
Basic Bitcoin Stamps, Collections, and SRC-20 tools
MCP client integration
Comprehensive test suite

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

View all tools

A Model Context Protocol server that enables interaction with Bitcoin Stamps data via the Stampchain API, providing tools for querying stamp information, collections, and blockchain data without requiring authentication.

Related MCP Servers

Bitcoin MCP Server
AbdelStark
A
security
A
license
A
quality
Facilitates interaction with the Bitcoin network via the Model Context Protocol, enabling key generation, address validation, transaction decoding, and blockchain data retrieval.
Last updated -
5
635
56
TypeScript
MIT License
Bybit MCP Server
sammcj
A
security
A
license
A
quality
A Model Context Protocol server that provides read-only access to Bybit's cryptocurrency exchange API, allowing users to query real-time cryptocurrency data using natural language.
Last updated -
9
5
12
TypeScript
MIT License
MCP Blockchain Query Server
pavel-bc
-
security
F
license
-
quality
A Model Context Protocol server providing tools for querying Bitcoin blockchain data via Blockchain Data and Query APIs, supporting various BTC information retrieval functions.
Last updated -
1
Python
Satstream MCP Serverofficial
satstream
A
security
A
license
A
quality
A Model Context Protocol server that enables querying Bitcoin blockchain data, including address information, transaction details, mempool statistics, and ordinals/runes data through the Satstream API.
Last updated -
37
TypeScript
MIT License

View all related MCP servers