RentCast

Acesse dados de propriedades, avaliações e estatísticas de mercado usando a API do RentCast.

Documentação

Servidor MCP RentCast

Um servidor Model Context Protocol (MCP) para a API RentCast. Ele dá ao Claude Desktop, Claude Code e outros clientes MCP acesso a registros de propriedades dos EUA, estimativas de valor e aluguel com comparáveis, listagens de venda e aluguel e estatísticas de mercado.

Você precisa de uma chave de API RentCast. Crie uma no seu painel da API RentCast.

🚀 Início Rápido

Há três maneiras de executar o servidor:

Extensão do Claude Desktop: um arquivo, sem necessidade de terminal.
Instalação local: clone o repositório e aponte o Claude Desktop ou o Claude Code para ele.
Implantação em contêiner: execute-o como um servidor HTTP com Docker.

1. Extensão do Claude Desktop

Compile a extensão (ou baixe rentcast-mcp.mcpb de um release):
```
npx @anthropic-ai/mcpb pack . rentcast-mcp.mcpb
```
Clique duas vezes em rentcast-mcp.mcpb, ou arraste-o para Configurações > Extensões do Claude Desktop.
Insira sua chave de API RentCast quando solicitado. O Claude Desktop a armazena como uma configuração sensível.

A extensão usa o tipo de servidor MCPB uv: o Claude Desktop instala as dependências fixadas de uv.lock no primeiro lançamento, então você não precisa ter o Python instalado.

2. Instalação Local

Instale o uv (recomendado):

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone este repositório:

git clone https://github.com/robcerda/rentcast-mcp-server.git
cd rentcast-mcp-server

Instale as dependências:

Usando uv (recomendado):
```
uv sync --locked
```
--locked instala exatamente o que uv.lock fixa, verificado contra os hashes que ele registra, e se recusa a re-resolver.

Usando pip:
```
pip install -r requirements-lock.txt --require-hashes
pip install -e . --no-deps
```
requirements-lock.txt é gerado a partir de uv.lock e fixa cada dependência com hashes, então o caminho do pip instala o mesmo conjunto que o do uv. pip install -r requirements.txt ainda funciona e instala exatamente o mesmo conjunto.
Defina sua chave de API. Crie um arquivo .env na raiz do projeto:
```
RENTCAST_API_KEY=your_api_key_here
```
Ou passe-o no bloco env da configuração do cliente abaixo.

Configure o Claude Desktop: Adicione isto ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "RentCast": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "run",
        "--locked",
        "--project",
        "/path/to/your/rentcast-mcp-server",
        "rentcast-mcp"
      ],
      "env": {
        "RENTCAST_API_KEY": "your_api_key_here"
      }
    }
  }
}

Importante: Substitua /path/to/your/rentcast-mcp-server pelo seu caminho real, e /opt/homebrew/bin/uv pela saída de which uv.

Reinicie o Claude Desktop após salvar a configuração.

OU configure o Claude Code:

claude mcp add rentcast -e RENTCAST_API_KEY=your_api_key_here -- \
  uv run --locked --project /path/to/your/rentcast-mcp-server rentcast-mcp

Se instalado via pip em vez de uv, use:

{
  "command": "python",
  "args": ["/path/to/your/rentcast-mcp-server/src/rentcast_mcp_server/server.py"]
}

Configuração

Variável	Obrigatória	Descrição
`RENTCAST_SURROGATE_KEY`	Não	Uma credencial substituta (`hsurr:...`) para enviar em vez da chave real. Preferida sobre `RENTCAST_API_KEY` quando definida
`RENTCAST_API_KEY`	Sim, a menos que uma substituta esteja definida	Sua chave de API RentCast
`RENTCAST_SUPPRESS_LOGGING`	Não	`true` pede ao RentCast para não registrar suas consultas e parâmetros de consulta
`RENTCAST_MCP_TRANSPORT`	Não	`stdio` (padrão), `streamable-http` ou `http`
`RENTCAST_MCP_HOST`	Não	Endereço de bind HTTP (padrão `127.0.0.1`)
`RENTCAST_MCP_PORT`	Não	Porta HTTP (padrão `8000`)
`RENTCAST_MCP_ALLOWED_HOSTS`	Não	Valores extras de `Host` para aceitar via HTTP, separados por vírgula
`RENTCAST_MCP_ALLOWED_ORIGINS`	Não	Valores extras de `Origin` do navegador para aceitar via HTTP, separados por vírgula

Cada configuração HTTP também tem uma flag de linha de comando: rentcast-mcp --help.

Credenciais substitutas

Se o seu ambiente emitir uma credencial substituta (uma string começando com hsurr:) no lugar da chave de API real, defina-a em RENTCAST_SURROGATE_KEY. O servidor a envia no cabeçalho X-Api-Key exatamente como fornecida, da mesma forma que envia uma chave real, e usa RENTCAST_API_KEY apenas quando nenhuma substituta está definida. Um valor em RENTCAST_SURROGATE_KEY que não comece com hsurr: interrompe o servidor com um erro em vez de recorrer à chave real.

Implantação em Contêiner

docker build -t rentcast-mcp .
docker run --rm -p 8000:8000 -e RENTCAST_API_KEY=your_api_key_here rentcast-mcp

A imagem serve HTTP transmitível na porta 8000 em /mcp. A validação de Host e Origin permanece ativa mesmo quando vinculada a 0.0.0.0, então um cliente que a acessa por um nome público precisa que esse nome seja permitido:

docker run --rm -p 8000:8000 \
  -e RENTCAST_API_KEY=your_api_key_here \
  -e RENTCAST_MCP_ALLOWED_HOSTS=mcp.example.com \
  rentcast-mcp

O transporte HTTP não tem autenticação própria. Qualquer pessoa que possa alcançar a porta pode gastar sua cota RentCast, então coloque-o atrás de uma VPN ou de um proxy reverso autenticado se estiver acessível fora da sua máquina.

✨ Recursos

🏠 Registros de Propriedades

Registros públicos de mais de 150 milhões de propriedades nos EUA: atributos, proprietário, avaliações fiscais, histórico de vendas e recursos. Consulte um endereço ou pesquise por cidade, estado, CEP ou um raio ao redor de um ponto.

💰 Estimativas de Valor e Aluguel

O modelo de avaliação automatizada da RentCast retorna uma estimativa de valor ou aluguel de longo prazo com uma faixa e as listagens comparáveis usadas para calculá-la. Ajuste os comparáveis com comp_count, max_radius e days_old, ou substitua os atributos da propriedade em questão.

📋 Listagens de Venda e Aluguel

Listagens ativas e inativas de venda e aluguel de longo prazo, com preço, datas de listagem, detalhes do agente e do escritório e histórico de listagem.

📈 Estatísticas de Mercado

Estatísticas de venda e aluguel para qualquer CEP: preço e aluguel médio, mediano, mínimo e máximo, preço por metro quadrado, dias no mercado, contagens de listagens, detalhamentos por tipo de propriedade e quartos e histórico mensal.

🔍 Consultas de Pesquisa

As ferramentas de pesquisa aceitam a sintaxe de consulta da RentCast:

Múltiplos valores com |: property_type="Condo|Townhouse", bedrooms="2|3"
Faixas inclusivas com : e * para uma extremidade aberta: bedrooms="2:4", price="*:500000", year_built="2000:*"
Até 500 resultados por solicitação, paginados com limit e offset. Defina include_total_count para obter o número total de correspondências.

🛠️ Ferramentas Disponíveis

Ferramenta	Descrição	Endpoint RentCast
`search_properties`	Pesquisar registros de propriedades	`/properties`
`get_random_properties`	Amostra aleatória de registros de propriedades	`/properties/random`
`get_property`	Um registro de propriedade por id	`/properties/{id}`
`get_value_estimate`	Estimativa de valor com vendas comparáveis	`/avm/value`
`get_rent_estimate`	Estimativa de aluguel de longo prazo com aluguéis comparáveis	`/avm/rent/long-term`
`search_sale_listings`	Pesquisar listagens de venda	`/listings/sale`
`get_sale_listing`	Uma listagem de venda por id	`/listings/sale/{id}`
`search_rental_listings`	Pesquisar listagens de aluguel de longo prazo	`/listings/rental/long-term`
`get_rental_listing`	Uma listagem de aluguel por id	`/listings/rental/long-term/{id}`
`get_market_statistics`	Estatísticas e histórico de mercado para um CEP	`/markets`

As ferramentas de pesquisa retornam {count, limit, offset, hasMore, results}, além de totalCount quando solicitado.

Prompts: property_analysis (valor, aluguel, comparáveis e mercado para um endereço) e market_overview (o mercado de venda e aluguel de um CEP).

📝 Exemplos de Uso

Valor e Aluguel para um Endereço

What is 5500 Grand Lake Dr, San Antonio, TX 78244 worth, and what would it rent for?

Encontrar Listagens

Find 3 bedroom houses for sale under $500k in 78704 listed in the last 30 days

Tendências do Mercado de Aluguel

Show rental market trends in ZIP code 90210 over the last year

Análise de Investimento

Compare the gross rental yield of condos and single family homes for sale in 33131

🔧 Solução de Problemas

`RentCast API error 401`

A chave de API está ausente ou inválida. Verifique RENTCAST_API_KEY, ou re-insira a chave nas configurações da extensão.

`RentCast API error 403`

A chave está restrita a outros endpoints ou endereços IP, ou há um problema de cobrança. Verifique seu painel da API.

`RentCast API error 429`

A RentCast permite 20 solicitações por segundo por chave. O servidor tenta novamente solicitações limitadas por taxa com backoff antes de relatar isso.

Resultados de pesquisa vazios

A RentCast relata "sem resultados" como uma lista results vazia. city e state diferenciam maiúsculas de minúsculas, e property_type deve corresponder exatamente, por exemplo, Single Family.

O servidor desconecta na inicialização

Verifique os logs MCP do cliente. A causa mais comum é um RENTCAST_API_KEY ausente, o que faz o servidor sair imediatamente.

Desenvolvimento

uv sync --locked --extra dev
uv run pytest
uv run ruff check .

Os testes são executados contra uma API RentCast falsa e nunca fazem solicitações reais.

Executando o servidor localmente

uv run rentcast-mcp

Para usar o MCP Inspector:

uv run mcp dev src/rentcast_mcp_server/server.py

Atualizando dependências

uv lock --upgrade-package <name>
uv export --frozen --no-emit-project --no-editable --no-dev \
  --format requirements-txt --output-file requirements-lock.txt

O CI falha se uv.lock, requirements-lock.txt e requirements.txt divergirem.

Compilando a extensão

npx @anthropic-ai/mcpb validate manifest.json
npx @anthropic-ai/mcpb pack . rentcast-mcp.mcpb

.mcpbignore mantém testes, arquivos de CI e ambientes locais fora do pacote. Quando você adicionar ou renomear uma ferramenta, atualize a lista tools em manifest.json; um teste verifica se ela corresponde ao servidor.

Licença

MIT