Stampchain MCP Server
OfficialProvides access to Bitcoin Stamps data, allowing queries for stamp information, collections, and SRC-20 token deployment and minting data on the Bitcoin blockchain.
Offers code generation for Express API endpoints that interact with Bitcoin Stamps data, including search functionality and rate limiting.
Provides assistance for integrating Bitcoin Stamps data into Next.js applications, particularly for SRC-20 token display and management.
Enables integration with PostgreSQL databases for storing and querying Bitcoin Stamps metadata and collection statistics.
Includes integration with Postman collections for exploring and testing the Stampchain API endpoints.
Offers code generation and integration assistance for building React components that display Bitcoin Stamps data, including galleries and collection dashboards.
Supports Redis integration for caching stamp data in backend services to improve performance of stamp-related applications.
Provides code generation for UI components styled with Tailwind CSS to display Bitcoin Stamps data and collections.
Supports generation of Vue.js components for Bitcoin Stamps integration, including gallery components that display stamp data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Stampchain MCP Server show me the most recent Bitcoin Stamps"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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+
Related MCP server: Satstream MCP Server
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-mcpInstall dependencies:
npm installBuild the project:
npm run buildTest 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 IDsearch_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 collectionsearch_collections- Search collections with filters
SRC-20 Tokens
get_token_info- Get detailed information about a specific SRC-20 tokensearch_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 versionDevelopment
Scripts
npm run dev- Start development server with hot reloadnpm run build- Build the TypeScript projectnpm run test- Run all testsnpm run test:watch- Run tests in watch modenpm run test:coverage- Run tests with coverage reportnpm run typecheck- TypeScript type checkingnpm run format- Format code with Prettiernpm 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:watchProject 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 implementationAPI 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 successfuldata- The requested data (stamps, collections, tokens)pagination- Pagination information when applicableerror- Error details if the request failed
Troubleshooting
Common Issues
Build Errors: Ensure you have Node.js 18+ and run
npm installfirstConnection 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 -- --debugOr 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 installStart development server:
npm run devRun tests in watch mode:
npm run test:watchValidate before commit:
npm run validate
Contributing
Fork the repository
Create a feature branch:
git checkout -b feature/new-featureMake your changes
Run tests:
npm testCommit your changes:
git commit -am 'Add new feature'Push to the branch:
git push origin feature/new-featureSubmit 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 validatebefore 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
Available Tools
13 toolsanalyze_stamp_codeC
Analyze the code structure and dependencies of a recursive stamp, including JavaScript parsing, dependency resolution, and pattern detection
Inputs: stamp_id (required), include_dependencies, max_depth, include_raw_content, +2 more.
analyze_stamp_patternsC
Analyze patterns across multiple recursive stamps to identify common libraries, frameworks, and coding techniques used in the ecosystem
Inputs: sample_size, pattern_types, complexity_analysis, min_occurrences, +2 more.
get_collectionB
Retrieve detailed information about a specific stamp collection by its ID
Inputs: collection_id (required), include_stamps, stamps_page, stamps_limit.
get_market_dataC
Retrieve market data for stamps with trading activity indicators (v2.3 feature)
Inputs: stamp_id, activity_level, min_floor_price, max_floor_price, +3 more.
get_recent_salesC
Retrieve recent stamp sales with enhanced transaction details (v2.3 feature)
Inputs: stamp_id, dayRange, fullDetails, page, +2 more.
get_recent_stampsC
Retrieve the most recently created Bitcoin stamps
Inputs: limit.
get_stampC
Retrieve detailed information about a specific Bitcoin stamp by its ID
Inputs: stamp_id (required), include_base64.
get_stamp_dependenciesB
Create a hierarchical dependency graph for a recursive stamp, showing all referenced stamps and their relationships
Inputs: stamp_id (required), max_depth, include_metadata, format, +1 more.
get_stamp_market_dataC
Retrieve detailed market data for a specific stamp (v2.3 feature)
Inputs: stamp_id (required).
get_token_infoC
Retrieve detailed information about a specific SRC-20 token by its ticker symbol
Inputs: tick (required), include_holders, include_transfers.
search_collectionsC
Search for stamp collections with various filtering criteria
Inputs: query, creator, sort_by, sort_order, +2 more.
search_stampsC
Search for Bitcoin stamps with various filtering criteria including creator, collection, and stamp type
Inputs: query, creator, collection_id, cpid, +5 more.
search_tokensC
Search for SRC-20 tokens with various filtering criteria
Inputs: query, deployer, min_holders, min_percent_minted, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools have distinct purposes targeting different resources (stamps, collections, tokens, market data), but there is some overlap between get_market_data and get_stamp_market_data which could cause confusion. The descriptions clarify that one is general and one is stamp-specific, but the naming similarity might lead to misselection.
Tool names follow a highly consistent verb_noun pattern throughout, with clear prefixes like get_, search_, and analyze_. All use snake_case consistently, making the set predictable and easy to understand at a glance.
With 13 tools, the count is well-scoped for a server focused on Bitcoin stamps, collections, tokens, and market data. Each tool appears to serve a specific function without redundancy, fitting the domain's complexity appropriately.
The tool set covers key operations like retrieval (get_), search, and analysis for stamps, collections, and tokens, with market data features included. Minor gaps might exist, such as no explicit update or delete tools, but these may not be needed for the domain's read-heavy nature, and agents can likely work around this.
Maintenance
Related MCP Connectors
Model Context Protocol server for Studex tools, notifications, and profile integrations
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server providing tools for querying Bitcoin blockchain data via Blockchain Data and Query APIs, supporting various BTC information retrieval functions.1-

Satstream MCP Serverofficial
AlicenseBqualityDmaintenanceA 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.37MIT
Blockscout MCP Serverofficial
FlicenseAqualityCmaintenanceA server that exposes blockchain data (balances, tokens, NFTs, contract metadata) via the Model Context Protocol, enabling AI agents and tools to access and analyze blockchain information contextually.1846-- AlicenseBqualityDmaintenanceA Model Context Protocol server that provides real-time Bitcoin blockchain and mempool data to AI clients, allowing access to comprehensive Bitcoin network information through various data tools.3114 npm5MIT