HTS MCP
Skip to Content
Getting Started

Getting Started

Get HTS MCP up and running with all three interfaces.

Prerequisites

  • Python 3.11 or higher
  • PostgreSQL with pgvector  extension (Supabase recommended)
  • OpenAI API key (for embeddings and enrichment)
  • An MCP-compatible client (e.g., Claude Desktop, Cursor) for MCP usage

Installation

git clone https://github.com/mfbaig35r/hts-api.git
cd hts-api
uv sync

Configuration

Copy the example environment file and fill in your credentials:

cp .env.example .env

Required settings:

DATABASE_URL=postgresql://user:pass@host:5432/dbname
OPENAI_API_KEY=sk-...

See Configuration for all 30+ settings.

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hts": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hts-api", "python", "-m", "hts.mcp"]
    }
  }
}

Claude Code

Add to your MCP settings:

{
  "hts": {
    "command": "uv",
    "args": ["run", "--directory", "/path/to/hts-api", "python", "-m", "hts.mcp"]
  }
}

Quick Verification

Check that the database is connected and populated:

uv run hts status

Expected output includes tariff count (~13,000), date range, embedding availability, enrichment status, and resource count.

Data Pipeline Quickstart

The full pipeline loads data, generates enrichments and embeddings, and builds the knowledge graph. Run these steps in order:

# 1. Load tariff data from source CSV
uv run hts load general_tariff_data.txt
 
# 2. Load sections and extract headings
uv run hts load-sections hts_sections.csv
 
# 3. Load chapters from USITC API
uv run hts load-chapters
 
# 4. Extract code references from descriptions
uv run hts extract-code-references
 
# 5. Load policy resources
uv run hts load-tariff-resources
 
# 6. Enrich HTS6 codes with AI descriptions
uv run hts enrich-hts6
 
# 7. Generate multi-level embeddings
uv run hts generate-multilevel-embeddings
 
# 8. Generate graph edge candidates via KNN
uv run hts generate-graph-edges
 
# 9. Classify edges with LLM
uv run hts classify-graph-edges

See Data Pipeline Workflows for detailed explanations of each step.

Next Steps

  • For Humans: Understanding HTS codes and tariff rates
  • For LLMs: MCP tool calling patterns for AI agents
  • MCP Tools: Complete MCP tool reference
  • REST API: HTTP endpoint documentation
DashboardFor Humans