What can you do with this server?

Query Brazilian national, state, and municipal holidays plus FEBRABAN banking calendar data. * Search holidays flexibly by date, type, UF, IBGE code, year, month, and banking status. * List national holidays, holidays by state or city, and bank holidays. * Check whether a date is a holiday or a banking business day, including reason and next business day. * List Brazilian states and search municipalities to find IBGE codes.

feriadosapi

by feriadosapi

Overview Schema Source Related Servers Discussions Admin

TypeScript

🇧🇷 Feriados API — MCP Server

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

⚡ Quick Start

Opção 1: URL Remota com OAuth 2.1 (Recomendado — Sem copiar chaves!)

Em clientes compatíveis com o padrão de autorização MCP (Cursor, Claude Desktop, Claude.ai, VS Code, ChatGPT, MCP Inspector), basta adicionar a URL remota limpa:

{
  "mcpServers": {
    "feriadosapi": {
      "url": "https://mcp.feriadosapi.com/api/mcp"
    }
  }
}

Ao conectar, seu navegador abrirá automaticamente a página da Feriados API para você entrar com sua conta (Google, GitHub ou E-mail), selecionar qual organização será debitada e autorizar o agente com OAuth 2.1 + PKCE.

Opção 2: URL Remota com API Key (BYOK / Legado)

Se o seu cliente MCP não usar OAuth interativo ou rodar em background, passe sua chave via header Authorization / X-API-Key ou query parameter ?apiKey=:

{
  "mcpServers": {
    "feriadosapi": {
      "url": "https://mcp.feriadosapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_sua_chave_aqui"
      }
    }
  }
}

Ou diretamente na URL:

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

💡 Crie uma conta gratuita em feriadosapi.com — acesso gratuito a feriados nacionais, estaduais, capitais e calendário bancário (60 req/min).

Opção 3: Via `npx` (Execução Local / `stdio`)

Execute localmente via Node.js passando sua FERIADOS_API_KEY:

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

Related MCP server: PH Holidays MCP

🛠️ Ferramentas Disponíveis

Ferramenta	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
`feriados_bancarios`	Feriados bancários do calendário FEBRABAN
`verificar_dia_util_bancario`	Verifica se uma data é dia útil bancário
`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

O servidor MCP suporta 3 modos de autenticação, todos integrados às cotas e métricas por usuário/conexão do seu Dashboard em feriadosapi.com:

OAuth 2.1 + PKCE S256 (Recomendado): Conecte-se diretamente a https://mcp.feriadosapi.com/api/mcp sem informar chave. O cliente MCP descobre automaticamente os endpoints RFC 9728 / RFC 8414 e abre o navegador para autorização e seleção da organização. Você pode pausar ou revogar o agente a qualquer momento na aba Chaves de API do Dashboard.
Via URL Remota com API Key (BYOK): Passe Authorization: Bearer sk_live_..., X-API-Key: sk_live_... ou ?apiKey=sk_live_... na URL do MCP.
Via stdio (Local via npx): Defina a variável de ambiente FERIADOS_API_KEY.

⚠️ Sem autenticação válida (OAuth 2.1 ou API Key), chamadas de ferramentas não são executadas e o servidor responde 401 Unauthorized iniciando o desafio OAuth.

🏗️ 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

Available Tools

9 tools

buscar_feriadosBuscar FeriadosA

Busca feriados brasileiros com filtros flexíveis. Use esta tool para consultas gerais quando precisar filtrar por múltiplos critérios ao mesmo tempo. Pode filtrar por data, tipo (NACIONAL/ESTADUAL/MUNICIPAL/FACULTATIVO), estado (UF), cidade (código IBGE), ano e mês. Para buscas mais específicas, prefira usar as tools especializadas (feriados_nacionais, feriados_por_estado, etc.). Retorna lista paginada de feriados com nome, data (DD/MM/YYYY), tipo, descrição e indicador bancário (FEBRABAN).

Inputs: uf, ano, date, ibge, +3 more.

buscar_municipiosBuscar MunicípiosA

Busca municípios brasileiros por estado. Retorna nome, UF e código IBGE de cada município. Use esta tool para descobrir o código IBGE de uma cidade antes de consultar feriados municipais com 'feriados_por_cidade'. Pode filtrar por UF para listar apenas municípios de um estado. O Brasil possui mais de 5.500 municípios; use o filtro de UF para resultados mais precisos.

Inputs: uf, page, limit.

feriados_bancariosFeriados Bancários (FEBRABAN)A

Lista todos os feriados bancários do calendário oficial FEBRABAN (Resolução 4.880/2020 do CMN). Inclui feriados nacionais + datas facultativas em que agências bancárias não funcionam: Carnaval (seg/ter), Quarta-feira de Cinzas, Corpus Christi e Véspera de Ano Novo (31/dez). Ideal para cálculos de vencimentos, compensações e prazos bancários. Pode filtrar por estado (UF) ou município (IBGE) para incluir feriados bancários estaduais/municipais.

Inputs: uf, ano, ibge, facultativos.

feriados_nacionaisFeriados NacionaisA

Lista todos os feriados nacionais do Brasil para um ano específico. Inclui feriados como Carnaval, Sexta-feira Santa, Tiradentes, Dia do Trabalho, Independência, Nossa Senhora Aparecida, Finados, Proclamação da República e Natal. Opcionalmente pode incluir feriados facultativos nacionais (Ponto Facultativo). Se nenhum ano for informado, retorna feriados de todos os anos disponíveis.

Inputs: ano, bancarios, facultativos.

feriados_por_cidadeFeriados por CidadeA

Lista todos os feriados de uma cidade brasileira (feriados nacionais + estaduais + municipais). Use quando o usuário perguntar sobre feriados em uma cidade específica. Requer o código IBGE do município. Se não souber o código IBGE, use primeiro a tool 'buscar_municipios' para encontrá-lo. Exemplos de códigos IBGE: São Paulo = 3550308, Rio de Janeiro = 3304557, Belo Horizonte = 3106200, Brasília = 5300108.

Inputs: ibge (required), ano, bancarios, facultativos.

feriados_por_estadoFeriados por EstadoA

Lista todos os feriados de um estado brasileiro (feriados nacionais + estaduais daquele UF). Use quando o usuário perguntar sobre feriados em um estado específico, como "feriados em São Paulo" ou "feriados do RJ". As siglas dos estados (UF) são: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO.

Inputs: uf (required), ano, bancarios, facultativos.

listar_estadosListar Estados do BrasilA

Lista todos os 27 estados brasileiros (26 estados + Distrito Federal) com suas siglas UF. Use quando precisar consultar as siglas dos estados ou quando o usuário perguntar "quais são os estados do Brasil". Retorna sigla (UF) e nome completo de cada estado.

Inputs: no named parameters.

verificar_dataVerificar se Data é FeriadoA

Verifica se uma data específica é feriado no Brasil. Use quando o usuário perguntar algo como "amanhã é feriado?", "25 de dezembro é feriado?", ou "segunda-feira vai ser feriado?". Retorna todos os feriados que caem naquela data (pode ter mais de um: nacional + municipal, por exemplo). Se retornar lista vazia, a data NÃO é feriado.

Inputs: data (required).

verificar_dia_util_bancarioVerificar Dia Útil BancárioA

Verifica se uma data é dia útil bancário (agências abrem normalmente). Use quando o usuário perguntar "o banco abre amanhã?", "quando vence o boleto?", "qual o próximo dia útil bancário?". Se não for dia útil, retorna o motivo (feriado bancário ou fim de semana) e o próximo dia útil bancário. Considera o calendário oficial FEBRABAN incluindo Carnaval, Quarta de Cinzas, Corpus Christi e 31/dez.

Inputs: data (required).

Tool Schema Changelog

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

Loading tool schema changelog…

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

A4.1/5.0

Scored 2026-05-01 01:40 across 9 tools

Disambiguation3/5

The tools have significant overlap, especially between 'buscar_feriados' and the specialized holiday tools (e.g., 'feriados_nacionais', 'feriados_por_estado'). While descriptions advise using specialized tools for specific queries, naming alone does not clearly distinguish purposes, potentially causing misselection.

Naming Consistency4/5

All tool names use snake_case, but they mix verb-initial patterns (e.g., 'buscar_feriados', 'listar_estados') with noun-initial patterns (e.g., 'feriados_nacionais', 'feriados_bancarios'). This slight inconsistency is noticeable but not chaotic.

Tool Count5/5

With 9 tools, the server covers the core operations for Brazilian holiday data: general search, specific location/type queries, and date/business day checks. This is a well-scoped count for a focused domain.

Completeness4/5

The tool surface covers most common holiday queries (national, state, city, bank holidays, date checking). A minor gap is the lack of a direct 'next holiday' tool, but 'verificar_dia_util_bancario' partially addresses this for banking days.

Maintenance

ActivityMaintained

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Holidays MCPA
io.github.Lulu-The-Narwhal
Free, keyless public holidays lookup for any country and year, plus single-date holiday checks.
Open Data Government Data Travel & Transportation
1
https://ads.getlulu.dev/holidays/mcp
Inday - Public Holiday API
io.github.gokhanibrikci
Public holiday data for 30+ countries. Check holidays, working days and calendars via AI assistants.
Government Data Search Open Data
2
https://inday.co/api/mcp
CNPJ e CEP
click.myagents
Empresa pelo CNPJ, CEP, feriados, DDD, bancos, NCM, Selic, CDI e IPCA, e conferência de CPF e CNPJ
Government Data Finance Location Services
1
https://brazil-lookup.mcp.myagents.click/mcp
Faceabot Public holidaysA
com.faceabot
Public holidays of about 200 countries: next holidays, is a given date a holiday. Free, no key.
Calendar Management Government Data Open Data
31
https://faceabot.com/tools-mcp/holidays

Related MCP Servers

brasil-api-mcp-server
Open Data Government Data Search
mauricio-cantu
F
license
B
quality
D
maintenance
Query a variety of data from Brasil resources seamlessly. Access information on postal codes, area codes, banks, holidays, taxes, and more through a unified interface. Enhance your AI agents and applications with rich and updated data from BrasilAPI effortlessly.
Updated 2 years ago (2025-03-20 20:13 UTC)
6
7
-
PH Holidays MCP
Government Data Open Data
GodModeArch
A
license
Not graded
quality
D
maintenance
Provides authoritative Philippine national holiday data sourced from official presidential proclamations, including regular, special, and Islamic holidays. It enables users to query specific dates, retrieve upcoming holidays, identify long weekends, and verify working day status.
Updated 8 months ago (2026-03-12 01:40 UTC)
16 npm
MIT
inday-api
Government Data Open Data Search
gokhanibrikci
A
license
Not graded
quality
C
maintenance
Public holiday data for 30+ countries. Check holidays, working days, and full calendars via AI assistants like Claude and Cursor.
Updated 7 months ago (2026-04-15 05:36 UTC)
MIT
Nager.Date MCP Server
Open Data Government Data Calendar Management
Dthen
A
license
Not graded
quality
B
maintenance
Provides public holidays, long weekends, and country data for 202 countries via the Nager.Date API, with client-side filtering and timezone-aware checks.
Updated 2 months ago (2026-09-27 09:01 UTC)
1
BSD Zero Clause