Skip to main content
Glama
cajuflow

Hotmart MCP Server

by cajuflow
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Hotmart MCP Server

License: MIT Python 3.11+

Servidor MCP (Model Context Protocol) para integração com APIs da Hotmart. Este servidor permite que agentes de IA gerenciem produtos, vendas e outras operações da Hotmart através de uma interface padronizada.

📋 Sobre

O Hotmart MCP Server é uma implementação do Model Context Protocol que conecta o Claude (e outros LLMs) diretamente às APIs da Hotmart. Desenvolvido com arquitetura modular e suporte a múltiplos transportes (STDIO local e SSE web), oferece uma integração robusta e flexível para automação de operações de produtores digitais.

Related MCP server: whop-mcp

📋 Pré-requisitos

  • Python 3.11 ou superior

  • Conta Hotmart com credenciais de API

  • uv (recomendado) ou pip para gerenciamento de dependências

  • Claude Desktop (para uso local) ou navegador web (para uso SSE)

🚀 Instalação

1. Clonar o Repositório

git clone https://github.com/cajuflow/hotmart-mcp.git
cd hotmart-mcp

2. Instalar Dependências

uv sync

3. Configurar Variáveis de Ambiente

# Copiar arquivo de exemplo
cp .env.example .env

# Editar com suas credenciais
nano .env

Conteúdo do .env:

# Credenciais Hotmart (obrigatório)
HOTMART_CLIENT_ID=seu_client_id_aqui
HOTMART_CLIENT_SECRET=seu_client_secret_aqui
HOTMART_BASIC_TOKEN=seu_basic_token_aqui

# Ambiente da Hotmart (sandbox ou production)
HOTMART_ENVIRONMENT=sandbox

# Configuração MCP (sse ou stdio)
TRANSPORT_TYPE=stdio

# Host e Porta para SSE Transport
MCP_HOST=0.0.0.0
MCP_PORT=8000

⚙️ Configuração Avançada

Host e Porta do Servidor

Para uso com Docker ou SSE transport, configure:

# Docker/Container (aceita conexões externas)
MCP_HOST=0.0.0.0
MCP_PORT=8000

# Local apenas (default)
MCP_HOST=127.0.0.1
MCP_PORT=8000

Uso comum por ambiente:

  • Local/STDIO: MCP_HOST=127.0.0.1 (padrão)

  • Docker/Container: MCP_HOST=0.0.0.0 (obrigatório)

  • Cloud/Produção: MCP_HOST=0.0.0.0 (recomendado)

4. Integração com Claude Desktop

Adicione ao seu claude_desktop_config.json:

stdio:

{
  "mcpServers": {
    "hotmart": {
      "command": "python",
      "args": ["C:/hotmart-mcp/hotmart_mcp.py"],
      "env": {
        "HOTMART_CLIENT_ID":"",
        "HOTMART_CLIENT_SECRET":"",
        "HOTMART_BASIC_TOKEN":"",
        "HOTMART_ENVIRONMENT": "production"
      }
    }
  }
}

5. Executar o Servidor

# Modo STDIO (padrão - Claude Desktop)
uv run python hotmart_mcp.py

# Modo SSE (aplicações web)
TRANSPORT_TYPE=sse uv run python hotmart_mcp.py

6. Docker (Opcional)

# Build da imagem
docker build -t hotmart-mcp .

# Executar container (usa .env automático)
docker run -p 8000:8000 --env-file .env hotmart-mcp

# Testar conectividade
python test_sse_poc.py

Importante: Para Docker, certifique-se que MCP_HOST=0.0.0.0 no .env!

Log esperado (Docker funcionando):

-> Running in SSE mode on 0.0.0.0:8000
INFO:     Uvicorn running on http://0.0.0.0:8000

🛠️ Ferramentas Disponíveis

  • get_hotmart_products: Lista produtos da sua conta Hotmart com filtros avançados.

  • get_hotmart_sales_history: Obtém histórico de vendas com filtros detalhados.

Testes

uv run python test_runner.py all

🆘 Suporte

Desenvolvido com ❤️ pela Cajuflow

Empoderando criadores digitais com soluções inteligentes de automação.

Available Tools

2 tools
get_hotmart_productsA

Get list of products from Hotmart account.

Args: status: Filter by product status. Options: DRAFT, ACTIVE, PAUSED, NOT_APPROVED, IN_REVIEW, DELETED, CHANGES_PENDING_ON_PRODUCT max_results: Maximum number of items per page (default: 50, max: 50) page_token: Cursor for pagination product_id: Unique identifier (ID) of the product (7 digits) format: Product format. Options: EBOOK, SOFTWARE, MOBILE_APPS, VIDEOS, AUDIOS, TEMPLATES, IMAGES, ONLINE_COURSE, SERIAL_CODES, ETICKET, ONLINE_SERVICE, ONLINE_EVENT, BUNDLE, COMMUNITY

Returns: JSON string containing list of products with their details

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNo
max_resultsNo
page_tokenNo
product_idNo
formatNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description alone must convey behavioral traits. It mentions the return format (JSON string) and lists parameters, but does not disclose authorization needs, rate limits, or potential impacts. For a read-only listing tool, this is minimally acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description starts with a clear one-line purpose, followed by a structured Args section. It is concise without unnecessary words, though the Args section could be slightly more compact. Still very readable and well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 optional parameters and the presence of an output schema (reducing need to describe return values), the description covers the main usage. However, it lacks any mention of authentication, rate limits, or pagination mechanics beyond the page_token parameter. It is complete enough for basic use but could be improved.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant meaning beyond the schema by enumerating each parameter with explanations, default values, and options (e.g., status and format enums, max_results limit, product_id format). With 0% schema coverage, this is crucial and well done.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get list of products from Hotmart account', specifying the verb 'get' and the resource 'products'. This distinguishes it from the sibling tool 'get_hotmart_sales_history', which retrieves sales history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool vs the sibling tool, nor does it mention prerequisites or when not to use it. Implicitly, the difference is clear (products vs sales history), but no exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_hotmart_sales_historyA

Get sales history from Hotmart account.

Args: transaction_status: Status da transação. Options: APPROVED, BLOCKED, CANCELLED, CHARGEBACK, COMPLETE, EXPIRED, NO_FUNDS, OVERDUE, PARTIALLY_REFUNDED, PRE_ORDER, PRINTED_BILLET, PROCESSING_TRANSACTION, PROTESTED, REFUNDED, STARTED, UNDER_ANALISYS, WAITING_PAYMENT max_results: Número máximo de itens por página (default: 50, max: 50) page_token: Cursor para paginação product_id: ID do produto (7 dígitos) start_date: Data inicial em milissegundos (timestamp desde 1970-01-01) end_date: Data final em milissegundos (timestamp desde 1970-01-01) sales_source: Código SRC da origem da venda transaction: Código único da transação (ex: HP17715690036014) buyer_name: Nome do comprador buyer_email: Email do comprador payment_type: Tipo de pagamento. Options: BILLET, CASH_PAYMENT, CREDIT_CARD, DIRECT_BANK_TRANSFER, DIRECT_DEBIT, FINANCED_BILLET, FINANCED_INSTALLMENT, GOOGLE_PAY, HOTCARD, HYBRID, MANUAL_TRANSFER, PAYPAL, PAYPAL_INTERNACIONAL, PICPAY, PIX, SAMSUNG_PAY, WALLET offer_code: Código da oferta commission_as: Como foi comissionado. Options: PRODUCER, COPRODUCER, AFFILIATE

Returns: JSON string containing sales history with detailed information

ParametersJSON Schema
NameRequiredDescriptionDefault
transaction_statusNo
max_resultsNo
page_tokenNo
product_idNo
start_dateNo
end_dateNo
sales_sourceNo
transactionNo
buyer_nameNo
buyer_emailNo
payment_typeNo
offer_codeNo
commission_asNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It implies a read-only operation and hints at pagination via 'max_results' and 'page_token' parameters, but does not explicitly state safe-to-call behavior, rate limits, or data volume considerations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a clear one-line purpose, followed by a parameter list. It is appropriately detailed for many parameters, but could be slightly more concise by removing redundant 'Options:' repetitions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (13 parameters, no schema coverage, and an output schema exists), the description sufficiently covers parameter semantics. It does not detail the output format beyond 'JSON string,' but the output schema likely provides that information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden. It provides detailed explanations for all 13 parameters, including enum options for transaction_status, payment_type, and commission_as, adding significant meaning beyond the schema's types and titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get sales history from Hotmart account,' identifying the verb and resource. It does not explicitly differentiate from the sibling tool 'get_hotmart_products,' but the tool name itself provides differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedget_hotmart_products
    • First observedget_hotmart_sales_history
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 2 tools

Disambiguation5/5

Each tool targets a distinct domain (products vs sales history) with no overlap in purpose, making it easy for an agent to select the correct tool.

Naming Consistency5/5

Both tools follow a consistent 'get_hotmart_<resource>' pattern, using snake_case and clear resource names.

Tool Count2/5

With only 2 tools, the server feels too minimal for a comprehensive Hotmart API integration; typical MCP servers offer more functionality.

Completeness1/5

The tool surface is severely incomplete, providing only read operations for products and sales, with no create, update, or delete capabilities.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • whop-mcp

    furkankoykiran
    A
    license
    A
    quality
    C
    maintenance
    A Model Context Protocol server that enables AI assistants to manage Whop.com business operations, including payments, memberships, products, promo codes, and affiliates.
    32
    5 npm
    6
    MIT

  • AI-Assisted CRM MCP Server

    MdJafirAshraf
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to perform CRM operations like creating contacts, managing deals, and updating leads through natural language using the Model Context Protocol.
    4
    -

  • Kommo CRM MCP Server

    E0DUAR
    A
    license
    C
    quality
    D
    maintenance
    Enables AI agents to manage Kommo CRM (formerly AmoCRM) entities including leads, contacts, companies, tasks, notes, pipelines, and products through natural language commands via the Model Context Protocol.
    39
    11 npm
    1
    MIT