Stampchain MCP Server
Provides tools for interacting with Bitcoin Stamps and SRC-20 token data via the Stampchain API, enabling querying of stamp details, collections, and tokens.
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 What is the total supply of the SRC-20 token STAMP?"
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: onchain-mcp
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), max_depth, include_raw_content, include_dependencies, +2 more.
analyze_stamp_patternsC
Analyze patterns across multiple recursive stamps to identify common libraries, frameworks, and coding techniques used in the ecosystem
Inputs: sort_by, sample_size, pattern_types, min_occurrences, +2 more.
get_collectionB
Retrieve detailed information about a specific stamp collection by its ID
Inputs: collection_id (required), stamps_page, stamps_limit, include_stamps.
get_market_dataC
Retrieve market data for stamps with trading activity indicators (v2.3 feature)
Inputs: page, stamp_id, page_size, activity_level, +3 more.
get_recent_salesC
Retrieve recent stamp sales with enhanced transaction details (v2.3 feature)
Inputs: page, dayRange, stamp_id, page_size, +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), format, max_depth, resolve_all, +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: page, query, creator, sort_by, +2 more.
search_stampsC
Search for Bitcoin stamps with various filtering criteria including creator, collection, and stamp type
Inputs: cpid, page, query, creator, +5 more.
search_tokensC
Search for SRC-20 tokens with various filtering criteria
Inputs: page, query, sort_by, deployer, +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
Several tools have unclear boundaries: get_stamp_market_data and get_market_data both cover market data, and analyze_stamp_code's dependency resolution overlaps heavily with get_stamp_dependencies. An agent could easily select the wrong tool for recursive-stamp analysis or market queries.
Tool names mostly follow a consistent get_/search_/analyze_ + noun pattern, with no mixed casing. Minor inconsistencies like get_stamp_market_data vs get_market_data and get_stamp_dependencies vs the analyze_ prefix for similar functions keep it from being perfect.
Thirteen tools is a reasonable size for an explorer/analytics server covering stamps, collections, tokens, and recursive code analysis. However, a few near-duplicate market-data and dependency tools could be consolidated without losing functionality.
The surface covers the main read/query workflows for stamps, collections, SRC-20 tokens, sales, market data, and recursive-stamp analysis. Obvious gaps are minor for a read-only API, such as no per-sale lookup or nested collection-stamp listing, but agents can complete most tasks.
Related MCP Connectors
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Bitcoin MCP: fees, tx proofs, address checks. Pay per call by x402, Lightning or a prepaid pass.
MEOK ABCI Bridge MCP — read-only Tendermint / Cosmos blockchain query for agents. Built-in registry
Public read-only MCP server for HODLXXI agent identity, trust, receipts, and verification.
Related MCP Servers
- AlicenseBqualityDmaintenanceA 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.13MIT
- AlicenseAqualityDmaintenanceProvides read-only access to Solana on-chain data, enabling natural language queries for wallet balances, token holdings, prices, transactions, and more via MCP-compatible clients.8MIT
- AlicenseAqualityDmaintenanceEnables MCP-compatible clients to query the RustChain blockchain, check balances, list miners, view epoch info, check network health, transfer RTC, and browse recent transactions and bounties.7MIT

fletch-mcpofficial
AlicenseBqualityBmaintenanceEnables MCP clients to query Robinhood Chain registry data, including verified stock token addresses, live token state, Chainlink feed rounds, holders, pools, bridge activity, and issuer documents.1720MIT