ProPublica MCP Server

Pesquise e analise dados do Formulário 990 de organizações sem fins lucrativos usando a API Nonprofit Explorer da ProPublica.

GitHub

Experimente este MCPPatrocinado

Documentação

ProPublica MCP Server

Um servidor Model Context Protocol (MCP) que fornece acesso à API Nonprofit Explorer da ProPublica, permitindo que modelos de IA pesquisem e analisem dados do Formulário 990 de organizações sem fins lucrativos para integração com CRM e pesquisa de prospects.

🚨 Mudanças Importantes na v1.0.0

A versão 1.0.0 introduz mudanças importantes com a implementação do transporte MCP 2025-03-26 Streamable HTTP:

Implantações remotas agora usam um único endpoint / em vez de /sse e /messages

A configuração do cliente MCP mudou para implantações em nuvem (veja a seção Uso abaixo)

Compatibilidade melhorada com Claude Desktop, Cursor e outros clientes MCP

Incompatível com versões anteriores para clientes MCP que esperam o antigo transporte SSE

Recursos

Pesquise organizações sem fins lucrativos por nome, localização e categoria
Recupere perfis detalhados de organizações e informações de contato
Acesse dados financeiros do Formulário 990 e histórico de declarações
Analise tendências financeiras ao longo de vários anos
Exporte dados em formatos prontos para CRM
Construído com FastMCP para desempenho ideal

🚀 Implantação com Um Clique

Implante o servidor ProPublica MCP instantaneamente na plataforma de nuvem de sua preferência:

DigitalOcean App Platform

Cloudflare Workers

Ambas as plataformas oferecem:

DigitalOcean: Implantação baseada em contêiner com escalonamento automático e monitoramento
Cloudflare: Implantação serverless com distribuição global de borda e zero cold starts

Início Rápido

Pré-requisitos

Cliente MCP compatível (Claude Desktop, Cursor, etc.)
Para desenvolvimento: Python 3.8 ou superior, Git

Instalação

Opção 1: Extensão DXT (Recomendado)

A maneira mais fácil de instalar o servidor ProPublica MCP é usando o formato de extensão DXT:

Instalar a partir dos Releases do GitHub:

Acesse a página de releases
Baixe o arquivo propublica-mcp-[version].dxt mais recente
Instale a extensão DXT:

Para Claude Desktop:

# Install from downloaded file
claude-desktop install propublica-mcp-[version].dxt

# Or install directly from GitHub release
claude-desktop install https://github.com/asachs01/propublica-mcp/releases/latest/download/propublica-mcp.dxt

Para outros clientes MCP: Siga as instruções de instalação DXT do seu cliente ou extraia o arquivo DXT para o diretório de extensões MCP.

Opção 2: Docker (Produção)

Para implantações em produção ou ambientes conteinerizados:

Início Rápido com Docker:

# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/asachs01/propublica-mcp:latest

# Run the server
docker run -it --rm ghcr.io/asachs01/propublica-mcp:latest

Usando Docker Compose:

Baixe o arquivo compose:

curl -O https://raw.githubusercontent.com/asachs01/propublica-mcp/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/asachs01/propublica-mcp/main/env.example

Configure o ambiente (opcional):

cp env.example .env
# Edit .env file with your preferred settings

Inicie o serviço:

docker-compose up -d

Opção 3: Implantação em Nuvem

DigitalOcean App Platform:

Clique no botão "Deploy to DO" acima
Conecte sua conta do GitHub (se ainda não estiver conectada)
Configure as variáveis de ambiente (opcional - os padrões são fornecidos)
Clique em "Deploy" - seu aplicativo estará no ar em minutos com uma URL pública

Cloudflare Workers:

Clique no botão "Deploy to Cloudflare Workers" acima
Conecte sua conta do GitHub e autorize o Cloudflare
Configure as variáveis de ambiente conforme necessário
Implante - sua função serverless estará disponível globalmente

🚀 Estratégia de Implantação em Produção

As implantações em nuvem são feitas apenas a partir do branch deploy, que contém versões estáveis e testadas:

Desenvolvimento: Todo o trabalho acontece no branch main

Releases: Quando tags são criadas (ex.: v0.2.0), o branch deploy é atualizado automaticamente

Plataformas em Nuvem: DigitalOcean e Cloudflare implantam apenas a partir do branch deploy

Benefícios: Garante que apenas versões estáveis e publicadas cheguem aos ambientes de produção

Opção 4: Instalação Local com Python (Desenvolvimento)

Para desenvolvimento e personalização:

Clone o repositório:

git clone https://github.com/asachs01/propublica-mcp.git
cd propublica-mcp

Crie e ative um ambiente virtual:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Instale as dependências:

pip install -r requirements.txt

Instale o pacote:

pip install -e .

Execute o servidor:

Para modo stdio (clientes MCP locais):

python -m propublica_mcp.server

Para modo HTTP (clientes MCP remotos):

python -m propublica_mcp.server --http --host 0.0.0.0 --port 8080

Opções disponíveis:

--http: Ativa o modo de servidor HTTP para clientes MCP remotos
--host: Host para vincular (padrão: 127.0.0.1)
--port: Porta para vincular (padrão: 8080)
--log-level: Define o nível de registro (DEBUG, INFO, WARNING, ERROR)

Uso com Clientes MCP

Este servidor implementa o protocolo de transporte MCP 2025-03-26 Streamable HTTP e pode ser usado com qualquer cliente MCP, incluindo Claude Desktop, Cursor e outras ferramentas compatíveis.

Para Extensão DXT (Recomendado):

Uma vez instalado como extensão DXT, o servidor será configurado automaticamente. A maioria dos clientes MCP detectará e carregará a extensão automaticamente.

Configuração DXT Manual (se necessário):

{
  "mcpServers": {
    "propublica-mcp": {
      "extension": "propublica-mcp.dxt",
      "description": "ProPublica Nonprofit Explorer MCP Server (DXT Extension)"
    }
  }
}

Para Implantação em Nuvem (Servidor MCP Remoto):

DigitalOcean/Cloudflare (Streamable HTTP):

Para servidores MCP Python remotos, você precisará usar um transporte HTTP. Adicione isto à configuração do seu cliente MCP:

{
  "mcpServers": {
    "propublica-mcp": {
      "transport": {
        "type": "http",
        "url": "https://propublica-mcp-lk97f.ondigitalocean.app"
      },
      "description": "ProPublica Nonprofit Explorer MCP Server (Remote)"
    }
  }
}

Para Instalação Local (transporte stdio):

{
  "mcpServers": {
    "propublica-mcp": {
      "command": "python",
      "args": ["-m", "propublica_mcp.server"],
      "cwd": "/path/to/propublica-mcp",
      "env": {}
    }
  }
}

Para Implantação Docker (transporte stdio):

{
  "mcpServers": {
    "propublica-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/asachs01/propublica-mcp:latest"
      ],
      "description": "ProPublica Nonprofit Explorer MCP Server"
    }
  }
}

Para Servidor HTTP Local (desenvolvimento):

# Start HTTP server locally
python -m propublica_mcp.server --http --host 0.0.0.0 --port 8080

Em seguida, configure como servidor remoto:

{
  "mcpServers": {
    "propublica-mcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8080"
      },
      "description": "ProPublica Nonprofit Explorer MCP Server (Local HTTP)"
    }
  }
}

Ferramentas da API

Ferramentas Principais

search_nonprofits: Pesquise organizações sem fins lucrativos
get_organization: Obtenha informações detalhadas da organização por EIN
get_organization_filings: Recupere declarações do Formulário 990 de uma organização

Ferramentas Avançadas

analyze_nonprofit_financials: Analise tendências financeiras ao longo de vários anos
search_similar_nonprofits: Encontre organizações semelhantes
export_nonprofit_data: Formate dados para importação em CRM

Fontes de Dados

Este servidor usa a API Nonprofit Explorer da ProPublica, que fornece:

Dados do Formulário 990 do IRS para organizações isentas de impostos
Perfis de organizações e informações de contato
Dados financeiros e histórico de declarações
Categorização NTEE e status 501(c)

Desenvolvimento

Estrutura do Projeto

propublica-mcp/
├── server/                    # DXT extension structure
│   ├── src/
│   │   └── propublica_mcp/
│   │       ├── __init__.py
│   │       ├── server.py
│   │       ├── api_client.py
│   │       ├── models.py
│   │       └── tools/
│   ├── requirements.txt
│   └── manifest.json         # DXT extension manifest
├── src/                      # Legacy source structure (for compatibility)
│   └── propublica_mcp/
├── tests/
├── config/
├── .github/
│   └── workflows/
│       └── build-dxt.yml     # Automated DXT packaging
├── Dockerfile
├── docker-compose.yml
├── env.example
├── requirements.txt
├── manifest.json             # Root DXT manifest
└── README.md

O projeto agora suporta tanto a estrutura tradicional de pacote Python quanto o novo formato de extensão DXT. O diretório server/ contém a estrutura compatível com DXT que é empacotada em arquivos .dxt durante os releases.

Desenvolvimento com Docker

Construindo a Imagem Docker

# Build the image
docker build -t propublica-mcp:dev .

# Or use docker-compose
docker-compose build

Executando o Ambiente de Desenvolvimento

# Run with docker-compose (includes volume mounts for development)
docker-compose -f docker-compose.yml -f docker-compose.override.yml up

# Run tests in container
docker run --rm -v $(pwd):/app propublica-mcp:dev pytest tests/ -v

Variáveis de Ambiente

O contêiner Docker suporta estas variáveis de ambiente:

LOG_LEVEL: Define o nível de registro (DEBUG, INFO, WARNING, ERROR)
API_RATE_LIMIT: Requisições por minuto (padrão: 60)
PROPUBLICA_API_BASE_URL: URL base da API (raramente precisa ser alterada)

Executando Testes

Testes Locais

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src/propublica_mcp

Testes com Docker

# Run tests in Docker
docker run --rm ghcr.io/asachs01/propublica-mcp:latest \
  python -m pytest tests/ -v

# Or with docker compose
docker compose run --rm propublica-mcp pytest tests/ -v

Construindo Extensões DXT

O projeto inclui empacotamento DXT automatizado via GitHub Actions. Os arquivos DXT são construídos automaticamente e anexados aos releases.

Construção DXT Automatizada (Recomendado)

Crie uma tag para acionar o empacotamento DXT automatizado:

# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0

Isso irá:

Empacotar o diretório server/ em um arquivo .dxt
Criar um release no GitHub com o arquivo DXT anexado
Construir e publicar imagens Docker no GitHub Container Registry

Construção DXT Manual

Para desenvolvimento ou testes:

# Create DXT package manually
cd server/
zip -r ../propublica-mcp-dev.dxt .

Publicação no GitHub Container Registry

O projeto inclui publicação automatizada via GitHub Actions, mas você também pode publicar manualmente:

Pré-requisitos

Token de Acesso Pessoal do GitHub com escopo packages:write

Autenticação no GitHub Container Registry:

echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_USERNAME --password-stdin

Publicação Automatizada (Recomendado)

Envie para o branch main ou crie uma tag para acionar builds automatizados:

# Trigger build for main branch
git push origin main

# Create and push a version tag (also builds DXT)
git tag v1.0.0
git push origin v1.0.0

Publicação Manual

Use o script fornecido (requer configuração local):

# Build and publish latest
./scripts/docker-publish.sh

# Build and publish specific version
./scripts/docker-publish.sh v1.0.0

Pacotes Disponíveis

Uma vez publicado, os seguintes pacotes estarão disponíveis:

Extensões DXT:

Mais recente: Disponível nos releases do GitHub
Versões com tag: propublica-mcp-v1.0.0.dxt
Download direto: https://github.com/asachs01/propublica-mcp/releases/latest/download/propublica-mcp.dxt

Imagens Docker:

Mais recente: ghcr.io/asachs01/propublica-mcp:latest
Versões com tag: ghcr.io/asachs01/propublica-mcp:v1.0.0
Builds de branch: ghcr.io/asachs01/propublica-mcp:main

Contribuindo

Siga o estilo de código existente
Adicione testes para novos recursos
Atualize a documentação conforme necessário
Garanta que todos os testes passem antes de enviar

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes

Suporte

Para problemas e perguntas:

Consulte a documentação
Revise os problemas existentes no GitHub
Crie um novo problema com informações detalhadas