What can you do with this server?

This server allows you to query Brazilian holidays (national, state, and municipal) in your AI agent using the Model Context Protocol (MCP). * Search holidays with flexible filters (buscar_feriados): Query by date, type (national/state/municipal/facultative), state (UF), city (IBGE code), year, and/or month. * List national holidays (feriados_nacionais): Retrieve all Brazilian national holidays for a specific year or all years, with optional facultative holidays. * List holidays by state (feriados_por_estado): Get all national + state-level holidays for a specific Brazilian state using its 2-letter UF code. * List holidays by city (feriados_por_cidade): Get all national + state + municipal holidays for a specific city using its IBGE code. * Check if a date is a holiday (verificar_data): Verify whether a specific date (YYYY-MM-DD) is a holiday in Brazil. * List all Brazilian states (listar_estados): Retrieve all 27 Brazilian states (26 states + Federal District) with their UF codes and full names. * Search municipalities (buscar_municipios): Find Brazilian municipalities by state (UF), returning their names and IBGE codes — useful before querying city-specific holidays.

🇧🇷 Feriados API — MCP Server

Consulte feriados brasileiros (nacionais, estaduais e municipais) direto no seu agente de IA favorito usando o Model Context Protocol.

npm version npm downloads GitHub issues GitHub last commit License: MIT

⚡ Quick Start

Opção 1: URL Remota (recomendado)

Adicione ao seu cliente de IA:

https://mcp.feriadosapi.com/api/mcp

Com sua própria API key (BYOK):

https://mcp.feriadosapi.com/api/mcp?apiKey=fapi_sua_chave_aqui

💡 Crie uma conta gratuita em feriadosapi.com para obter sua API key — acesso ilimitado a feriados nacionais, estaduais e capitais (60 req/min).

Opção 2: Via npx (local)

Obtenha uma API key gratuita em feriadosapi.com e configure:

{
  "mcpServers": {
    "feriadosapi": {
      "command": "npx",
      "args": ["-y", "@feriados-api/mcp-server"],
      "env": {
        "FERIADOS_API_KEY": "fapi_sua_chave_aqui"
      }
    }
  }
}

🛠️ Tools Disponíveis

Tool	Descrição
`buscar_feriados`	Busca com filtros flexíveis (data, tipo, UF, IBGE, ano, mês)
`feriados_nacionais`	Feriados nacionais do Brasil
`feriados_por_estado`	Feriados por estado (UF)
`feriados_por_cidade`	Feriados por cidade (código IBGE)
`verificar_data`	Verifica se uma data é feriado
`listar_estados`	Lista estados brasileiros
`buscar_municipios`	Busca municípios por UF

🔧 Configuração por Cliente

Claude Desktop / Claude Code

{
  "mcpServers": {
    "feriadosapi": {
      "command": "npx",
      "args": ["-y", "@feriados-api/mcp-server"],
      "env": {
        "FERIADOS_API_KEY": "fapi_sua_chave_aqui"
      }
    }
  }
}

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "feriadosapi": {
      "command": "npx",
      "args": ["-y", "@feriados-api/mcp-server"],
      "env": {
        "FERIADOS_API_KEY": "fapi_sua_chave_aqui"
      }
    }
  }
}

GitHub Copilot

// Configuração do GitHub Copilot MCP
{
  "github.copilot.mcp.servers": {
    "feriadosapi": {
      "command": "npx",
      "args": ["-y", "@feriados-api/mcp-server"],
      "env": {
        "FERIADOS_API_KEY": "fapi_sua_chave_aqui"
      }
    }
  }
}

Windsurf

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "feriadosapi": {
      "command": "npx",
      "args": ["-y", "@feriados-api/mcp-server"],
      "env": {
        "FERIADOS_API_KEY": "fapi_sua_chave_aqui"
      }
    }
  }
}

Antigravity (Gemini Code Assist)

// .gemini/settings.json
{
  "mcpServers": {
    "feriadosapi": {
      "command": "npx",
      "args": ["-y", "@feriados-api/mcp-server"],
      "env": {
        "FERIADOS_API_KEY": "fapi_sua_chave_aqui"
      }
    }
  }
}

Gemini CLI

// ~/.gemini/settings.json
{
  "mcpServers": {
    "feriadosapi": {
      "command": "npx",
      "args": ["-y", "@feriados-api/mcp-server"],
      "env": {
        "FERIADOS_API_KEY": "fapi_sua_chave_aqui"
      }
    }
  }
}

OpenAI Codex CLI

// ~/.codex/config.json
{
  "mcpServers": {
    "feriadosapi": {
      "command": "npx",
      "args": ["-y", "@feriados-api/mcp-server"],
      "env": {
        "FERIADOS_API_KEY": "fapi_sua_chave_aqui"
      }
    }
  }
}

ChatGPT / OpenAI Agents

URL: https://mcp.feriadosapi.com/api/mcp?apiKey=SUA_API_KEY

💬 Exemplos de uso

Após configurar, pergunte ao seu agente:

"Quais são os feriados de São Paulo em 2026?"
"Amanhã é feriado?"
"Quando é o Carnaval?"
"Quais feriados caem na sexta-feira em 2026?"
"Qual o código IBGE de Curitiba?"

🔑 Autenticação

Uma API key é obrigatória. Crie uma conta gratuita em feriadosapi.com (acesso ilimitado, 60 req/min) e passe sua chave:

Via URL remota: ?apiKey=fapi_xxx na URL do MCP
Via stdio (local): env var FERIADOS_API_KEY

⚠️ Sem uma API key válida, todas as chamadas retornarão erro de autenticação.

🏗️ Desenvolvimento Local

# Clonar o repositório
git clone https://github.com/feriadosapi/feriadosapi-mcp.git
cd feriadosapi-mcp

# Instalar dependências
npm install

# Configurar variáveis de ambiente
cp .env.example .env.local
# Editar .env.local com sua FERIADOS_API_KEY

# Rodar em desenvolvimento
npm run dev

# Build do stdio (para publicação npm)
npm run build:stdio

📖 Links Úteis

📄 Licença

MIT

feriadosapi