TapTools API MCP

View original on GitHub

A Python-based Model Context Protocol (MCP) server that provides access to the TapTools API , enabling Large Language Models (LLMs) (like Claude or GPT) to fetch Cardano-related data (tokens, NFTs, market info, etc.). This server standardizes TapTools API operations into MCP “tools,” allowing easy integration into AI workflows.

Features

Async Implementation: Uses modern Python async patterns and httpx for non-blocking IO.
Secure Authentication: Reads TAPTOOLS_API_KEY from environment variables or .env file.
MCP-Ready: Exposes TapTools functionality as “tools” accessible by any MCP-compliant client.
Token Operations: Pricing, top tokens, market cap data, volume stats, and more.
NFT Operations: NFT collection stats, trades, listings, distribution, etc.
Market Data: Aggregated stats on volume, addresses, holders, and more.
Integration & Onchain: Access to onchain data, block info, events, DEX pairs, etc.
Wallet Data: Portfolio positions, token/NFT holdings, transaction history, trades.

Quick Start

Clone the repository:


git clone https://github.com/yourusername/taptools-api-mcp.git
cd taptools-api-mcp

Create and activate a virtual environment:


python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:
```
pip install -e .
```
Set up your TapTools API key:
- Option A: Add to your .env file:
```
TAPTOOLS_API_KEY=your-real-taptools-api-key
```
- Option B: Set the environment variable:
```
export TAPTOOLS_API_KEY="your-real-taptools-api-key"
```
Run the MCP server:
```
python -m taptools_api_mcp
```
By default, it will run on standard input/output (stdio) for MCP integration.
Test the connection (optional):
```
python test_connection.py
```

Usage Example

If you have an MCP client (such as the mcp Python CLI tools), you can start the server and call any of the available tools:


# In one terminal, start the server:
python -m taptools_api_mcp
 
# In another terminal (or from the same, if you prefer):
mcp cli

Once inside the mcp cli, you can call tools like:


> tool verify_connection

This will verify that your TapTools API key is valid and accessible.

Or, for example, to get token market cap info:


> tool get_token_mcap {"unit": "lovelace"}

You should receive JSON data with the token’s market cap, price, supply, etc.

API Documentation: MCP Tools

Below is a list of available MCP tools, their parameters, and brief descriptions. These tools must be called with the correct JSON payloads. All JSON requests must match the Pydantic models found in src/taptools_api_mcp/models/.

1. verify_connection

Description: Verify TapTools API authentication.
Parameters: (No parameters.)
Sample Usage:
```
{ }
```

2. get_token_mcap

Description: Get token market cap info.

Parameters (TokenMcapRequest):


{
  "unit": "string"    // required: token unit identifier
}

Sample Usage:
```
{
  "unit": "lovelace"
}
```

3. get_token_holders

Description: Get total number of token holders.

Parameters (TokenHoldersRequest):


{
  "unit": "string"    // required: token unit identifier
}

Sample Usage:
```
{
  "unit": "lovelace"
}
```

4. get_token_holders_top

Description: Get top token holders.

Parameters (TokenTopHoldersRequest):


{
  "unit": "string",   // required
  "page": "number",   // optional (default 1)
  "per_page": "number"// optional (default 20)
}

Sample Usage:


{
  "unit": "some_token_unit",
  "page": 1,
  "per_page": 5
}

5. get_nft_asset_sales

Description: Get NFT asset sales history.

Parameters (NFTAssetSalesRequest):


{
  "policy": "string", // required: NFT policy ID
  "name": "string"    // optional: NFT name
}

Sample Usage:


{
  "policy": "abc123polid",
  "name": "coolNFT"
}

6. get_nft_collection_stats

Description: Get NFT collection stats.

Parameters (NFTCollectionStatsRequest):


{
  "policy": "string"  // required: NFT collection policy ID
}

Sample Usage:
```
{
  "policy": "abc123polid"
}
```

7. get_market_stats

Description: Get market-wide statistics.

Parameters (MarketStatsRequest):


{
  "quote": "string"    // optional, default "ADA"
}

Sample Usage:
```
{
  "quote": "USD"
}
```

8. get_integration_asset

Description: Get asset details by ID (integration endpoint).

Parameters (IntegrationAssetRequest):


{
  "id": "string"       // required: ID of the asset
}

Sample Usage:
```
{
  "id": "asset123abc"
}
```

9. get_asset_supply

Description: Get onchain asset supply.

Parameters (AssetSupplyRequest):


{
  "unit": "string"     // required: token unit identifier
}

Sample Usage:
```
{
  "unit": "lovelace"
}
```

10. get_wallet_portfolio

Description: Get wallet portfolio positions.

Parameters (WalletPortfolioPositionsRequest):


{
  "address": "string"  // required: wallet address
}

Sample Usage:
```
{
  "address": "addr1xyz..."
}
```

(Additional endpoints for tokens, NFTs, onchain, etc. can be added in the same format if needed. See the src/taptools_api_mcp/models/ folder for more possible requests.)

Deployment

You can containerize or host this Python MCP server on services like AWS ECS, Azure Container Instances, or Google Cloud Run. Make sure to securely store your TAPTOOLS_API_KEY as a secret. For Docker-based deployment:


# Example Dockerfile snippet
FROM python:3.10-slim
 
WORKDIR /app
COPY . /app
RUN pip install -e .
 
# environment variable for TapTools API key
ENV TAPTOOLS_API_KEY=your-real-taptools-api-key
 
CMD ["python", "-m", "taptools_api_mcp"]

Note: The server listens on stdio by default, per the MCP spec. For advanced deployment or custom integration, you can adapt server.py to run with alternative transports (like sockets) if your environment requires it.