# Servidor MCP para IAs
URL: /docs/mcp.mdx

Como integrar a Brapi com assistentes de IA usando o Model Context Protocol (MCP)

***

title: Servidor MCP para IAs
description:
Como integrar a Brapi com assistentes de IA usando o Model Context Protocol
(MCP)
-----

O **Model Context Protocol (MCP)** é um protocolo que permite aos assistentes de
IA acessar dados externos em tempo real. O servidor MCP da Brapi fornece
integração direta com dados financeiros brasileiros, permitindo que LLMs
consultem cotações, históricos e indicadores econômicos atualizados durante
conversas.

## O que é o MCP da Brapi

O servidor MCP da Brapi é uma implementação do Model Context Protocol que expõe
as funcionalidades da API Brapi para assistentes de IA compatíveis. Através
dele, você pode:

* Consultar cotações de ações da B3 em tempo real
* Obter dados históricos e análises fundamentalistas
* Acessar preços de criptomoedas e taxas de câmbio
* Consultar indicadores econômicos brasileiros

### Funcionamento

Quando configurado, o servidor MCP permite que assistentes de IA façam consultas
como:

```txt
Analise o desempenho da PETR4 no último mês
```

```txt
Compare as principais ações do Ibovespa hoje
```

O assistente automaticamente utiliza as ferramentas MCP para buscar dados
atualizados da Brapi e fornecer respostas precisas.

## Instalação

### Requisitos

* Node.js >= v18.0.0
* Cliente MCP compatível (Cursor, Claude Desktop, VS Code, Windsurf, etc.)
* Token da API Brapi ([obtenha gratuitamente](https://brapi.dev))

<Tabs items={['Cursor', 'Claude Desktop', 'VS Code', 'Windsurf', 'Cline', 'Zed']}>
  <Tab value="Cursor">
    ### Cursor

    Configure o servidor MCP editando o arquivo `~/.cursor/mcp.json` (global) ou
    `.cursor/mcp.json` (projeto específico).

    **Configuração:**

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer ${BRAPI_API_KEY}"
          ],
          "env": {
            "BRAPI_API_KEY": "SEU_TOKEN"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab value="Claude Desktop">
    ### Claude Desktop

    Edite o arquivo de configuração `claude_desktop_config.json`:

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer SEU_TOKEN"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab value="VS Code">
    ### VS Code

    Configure no arquivo de configuração MCP do VS Code:

    ```json
    {
      "mcp": {
        "servers": {
          "brapi": {
            "command": "npx",
            "args": [
              "mcp-remote",
              "https://brapi.dev/api/mcp/mcp",
              "--header",
              "Authorization:Bearer SEU_TOKEN"
            ]
          }
        }
      }
    }
    ```
  </Tab>

  <Tab value="Windsurf">
    ### Windsurf

    Configure no arquivo de configuração MCP do Windsurf:

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer ${BRAPI_API_KEY}"
          ],
          "env": {
            "BRAPI_API_KEY": "SEU_TOKEN"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab value="Cline">
    ### Cline

    **Configuração:**

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer SEU_TOKEN"
          ],
          "disabled": false,
          "autoApprove": []
        }
      }
    }
    ```
  </Tab>

  <Tab value="Zed">
    ### Zed

    Configure no arquivo `settings.json` do Zed:

    ```json
    {
      "context_servers": {
        "Brapi": {
          "command": {
            "path": "npx",
            "args": [
              "mcp-remote",
              "https://brapi.dev/api/mcp/mcp",
              "--header",
              "Authorization:Bearer SEU_TOKEN"
            ]
          },
          "settings": {}
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **Obtendo sua Chave da API**

  1. Acesse [brapi.dev](https://brapi.dev) e crie uma conta
  2. No dashboard, gere uma chave da API
  3. Substitua `SEU_TOKEN` pela sua chave
</Callout>

## Ferramentas Disponíveis

O servidor MCP expõe as seguintes ferramentas para assistentes de IA:

### Ferramentas Públicas (Sem Autenticação)

* `get_available_stocks` - Lista ações e índices brasileiros com filtros
  avançados (setor, tipo, busca, ordenação)
* `get_available_currencies` - Lista pares de moedas disponíveis
* `get_available_cryptocurrencies` - Lista criptomoedas disponíveis
* `get_available_inflation_countries` - Lista países com dados de inflação

### Ferramentas Premium (Chave da API Obrigatória)

* `get_stock_quotes` - Cotações e dados históricos de ações
* `get_currency_rates` - Taxas de câmbio em tempo real
* `get_crypto_prices` - Preços de criptomoedas
* `get_inflation_data` - Dados de inflação
* `get_prime_rate_data` - Dados da taxa básica de juros

### Autenticação

O servidor MCP suporta os mesmos métodos de autenticação da API REST:

* **Header Authorization:** `Authorization: Bearer sua_chave_api` (recomendado)
* **Header Authorization:** `Authorization: sua_chave_api`
* **Query parameter:** `?token=sua_chave_api`

## Dicas de Uso

### Regras Automáticas

Configure regras no seu cliente para invocar automaticamente a Brapi em
consultas financeiras:

**Windsurf (`.windsurfrules`):**

```toml
[[calls]]
match = "quando o usuário solicita dados financeiros, cotações de ações, preços de criptomoedas ou análise de mercado"
tool  = "brapi"
```

**Cursor:** Configure em `Settings > Rules`

### Especifique Símbolos

Para consultas mais eficientes, mencione os tickers diretamente:

```txt
Analise o desempenho da PETR4 nos últimos 3 meses e compare com VALE3
```

### Filtros Avançados

A ferramenta `get_available_stocks` suporta filtros avançados que permitem
consultas mais específicas:

**Por Setor:**

* `Finance` - Bancos e instituições financeiras
* `Energy Minerals` - Petróleo e energia
* `Technology Services` - Empresas de tecnologia
* `Health Services` - Saúde e medicina
* `Retail Trade` - Comércio varejista
* `Utilities` - Energia elétrica e saneamento

**Por Tipo:**

* `stock` - Ações ordinárias e preferenciais
* `fund` - Fundos imobiliários (FIIs)
* `bdr` - Brazilian Depositary Receipts

**Ordenação:**

* `volume` - Volume de negociação
* `market_cap_basic` - Valor de mercado
* `change` - Variação percentual
* `close` - Preço de fechamento
* `name` - Ordem alfabética

## Exemplos de Consultas

Com o MCP configurado, você pode fazer perguntas naturais como:

### Análise de Ações

```txt
"Analise o desempenho das ações da Petrobras (PETR4) no último mês e compare com o setor de energia"
```

```txt
"Quais são as 5 ações com melhor performance no Ibovespa hoje?"
```

```txt
"Mostre o histórico de dividendos da Vale (VALE3) nos últimos 2 anos"
```

### Câmbio e Economia

```txt
"Qual é a taxa de câmbio atual USD-BRL e como ela se compara com a média dos últimos 30 dias?"
```

```txt
"Mostre as principais moedas em relação ao Real brasileiro hoje"
```

### Criptomoedas

```txt
"Qual é o preço atual do Bitcoin em Real brasileiro?"
```

```txt
"Compare os preços das principais criptomoedas (BTC, ETH, ADA) em BRL"
```

### Descoberta de Mercado

```txt
"Mostre todas as ações de bancos brasileiros disponíveis"
```

```txt
"Liste as principais empresas de tecnologia listadas na B3"
```

```txt
"Quais são os fundos imobiliários (FIIs) com maior volume de negociação?"
```

```txt
"Mostre as ações do setor de energia ordenadas por valor de mercado"
```

```txt
"Liste todos os BDRs disponíveis ordenados alfabeticamente"
```

O assistente utilizará automaticamente as ferramentas MCP para buscar dados
atualizados.

## Solução de Problemas

<Tabs items={['Erros de Módulo', 'Problemas de Token', 'Configuração TLS', 'Erros de Cliente']}>
  <Tab value="Erros de Módulo">
    ### Erros de Módulo Não Encontrado

    Se você encontrar `ERR_MODULE_NOT_FOUND`, tente usar `bunx` em vez de `npx`:

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "bunx",
          "args": [
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer ${BRAPI_API_KEY}"
          ],
          "env": {
            "BRAPI_API_KEY": "SEU_TOKEN"
          }
        }
      }
    }
    ```

    Isso frequentemente resolve problemas de resolução de módulos em ambientes onde
    `npx` não instala ou resolve pacotes adequadamente.
  </Tab>

  <Tab value="Problemas de Token">
    ### Problemas de Token de API

    **"Token de autenticação obrigatório" (TOKEN\_REQUIRED)**

    * Certifique-se de que está fornecendo o cabeçalho Authorization com seu token
    * Verifique se seu token está copiado corretamente do dashboard
    * Para ferramentas premium, o token é obrigatório

    **"Token de API inválido ou expirado" (TOKEN\_INVALID)**

    * Verifique se seu token não expirou no dashboard da Brapi
    * Regenere seu token se necessário
    * Certifique-se de não ter espaços extras no token
  </Tab>

  <Tab value="Configuração TLS">
    ### Problemas de TLS/Certificado

    Use a flag `--experimental-fetch` para contornar problemas relacionados ao TLS:

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "npx",
          "args": [
            "--node-options=--experimental-fetch",
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer SEU_TOKEN"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab value="Erros de Cliente">
    ### Erros Gerais do Cliente MCP

    1. Tente adicionar `@latest` ao nome do pacote
    2. Use `bunx` como alternativa ao `npx`
    3. Considere usar `deno` como outra alternativa
    4. Certifique-se de estar usando Node.js v18 ou superior para suporte nativo ao
       fetch

    **Exemplo com Deno:**

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "deno",
          "args": [
            "run",
            "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION",
            "--allow-net",
            "npm:mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer SEU_TOKEN"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Segurança

O servidor MCP implementa as seguintes práticas de segurança:

* **Autenticação obrigatória** para ferramentas premium
* **Transmissão segura** via HTTPS/TLS
* **Validação de tokens** a cada requisição
* **Validação de parâmetros** de entrada
* **Controle de acesso** baseado no plano de assinatura

## Limites da API

As requisições MCP seguem os mesmos limites da API REST:

* **Plano Gratuito:** Até 15.000 requisições por mês
* **Plano Startup:** Até 150.000 requisições por mês
* **Plano Pro:** Até 500.000 requisições por mês

Consulte os [planos disponíveis](https://brapi.dev/pricing) para mais detalhes
sobre recursos e funcionalidades de cada plano.

## Clientes Compatíveis

O servidor MCP é compatível com qualquer cliente que suporte o protocolo MCP:

* **Cursor** - Editor de código com IA
* **Claude Desktop** - Aplicativo desktop do Anthropic
* **VS Code** - Com extensões MCP
* **Windsurf** - IDE com IA integrada
* **Cline** - Assistente de desenvolvimento
* **Zed** - Editor colaborativo
* **Outros clientes MCP** - Qualquer ferramenta compatível

## Próximos Passos

1. [Obtenha sua chave da API](https://brapi.dev)
2. Configure seu cliente MCP seguindo as instruções acima
3. Comece a fazer consultas financeiras em linguagem natural

<Callout type="info">
  **Recursos Relacionados**

  * [Documentação da API REST](/docs)
  * [Exemplos de integração](/docs/examples)
  * [Suporte](https://brapi.dev/contact)
</Callout>

***

<Callout type="warn">
  **Aviso Legal**

  Os dados são fornecidos apenas para fins informativos e não constituem
  aconselhamento financeiro. Consulte sempre um profissional qualificado antes de
  tomar decisões de investimento.
</Callout>


