Skip to main content
Glama
Stampchain MCP Server

Stampchain MCP Server

Stampchain MCP Server

CI npm version TypeScript License: MIT Node.js MCP Stampchain API

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

  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

Available Tools

13 tools
analyze_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

    B3.1/5.0

    Scored across 13 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      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.
      13
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      8
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      17
      20
      MIT