Skip to main content
Glama

Stampchain MCP Server

Official
by stampchain-io
GitHub
TypeScript
MIT License
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

  1. Clone the repository:
    git clone https://github.com/stampchain-io/stampchain-mcp.git cd stampchain-mcp
  2. Install dependencies:
    npm install
  3. Build the project:
    npm run build
  4. 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:

  1. Configuration file (JSON format)
  2. Environment variables
  3. 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

  1. Build Errors: Ensure you have Node.js 18+ and run npm install first
  2. Connection Issues: Check that the Stampchain API is accessible
  3. 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

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

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/new-feature
  3. Make your changes
  4. Run tests: npm test
  5. Commit your changes: git commit -am 'Add new feature'
  6. Push to the branch: git push origin feature/new-feature
  7. 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

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
Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
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.

  1. Features
    1. Quick Start
      1. Prerequisites
      2. Installation
      3. MCP Client Integration
    2. Available Tools
      1. Bitcoin Stamps
      2. Stamp Collections
      3. SRC-20 Tokens
    3. Configuration
      1. Example Configuration File
      2. Environment Variables
      3. Command Line Usage
    4. Development
      1. Scripts
      2. Testing
      3. Project Structure
    5. API Reference
      1. Tool Parameters
      2. Response Format
    6. Troubleshooting
      1. Common Issues
      2. Debugging
    7. Development
      1. Test Coverage
      2. Detailed Testing Commands
      3. Development Workflow
    8. Contributing
      1. Code Style
    9. License
      1. Support
        1. Changelog
          1. v0.2.0
          2. v0.1.0

        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 -
          7
          478
          56
          MIT License
          • Apple

        • 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 -
          12
          1
          12
          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
          • Linux
          • Apple

        • 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
          MIT License

        View all related MCP servers

        New MCP Servers

        MCP directory API

        We provide all the information about MCP servers via our MCP API.

        curl -X GET 'https://glama.ai/api/mcp/v1/servers/stampchain-io/stampchain-mcp'

        If you have feedback or need assistance with the MCP directory API, please join our Discord server