ProPublica MCP Server

Busca y analiza datos del Formulario 990 de organizaciones sin fines de lucro utilizando la API de Nonprofit Explorer de ProPublica.

GitHub

Documentación

Servidor MCP de ProPublica

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso a la API de Nonprofit Explorer de ProPublica, permitiendo a los modelos de IA buscar y analizar los datos del Formulario 990 de organizaciones sin fines de lucro para la integración con CRM e investigación de prospectos.

🚨 Cambios importantes en v1.0.0

La versión 1.0.0 introduce cambios importantes con la implementación del transporte HTTP Streamable MCP 2025-03-26:

Implementaciones remotas ahora usan un único endpoint / en lugar de /sse y /messages

La configuración del cliente MCP ha cambiado para implementaciones en la nube (consulte la sección Uso a continuación)

Compatibilidad mejorada con Claude Desktop, Cursor y otros clientes MCP

No compatible con versiones anteriores de clientes MCP que esperaban el transporte SSE antiguo

Características

Buscar organizaciones sin fines de lucro por nombre, ubicación y categoría
Recuperar perfiles detallados de organizaciones e información de contacto
Acceder a datos financieros del Formulario 990 e historial de presentaciones
Analizar tendencias financieras a lo largo de múltiples años
Exportar datos en formatos listos para CRM
Construido con FastMCP para un rendimiento óptimo

🚀 Implementación con un clic

Implemente el servidor MCP de ProPublica instantáneamente en su plataforma en la nube preferida:

Plataforma de aplicaciones de DigitalOcean

Cloudflare Workers

Ambas plataformas ofrecen:

DigitalOcean: Implementación basada en contenedores con escalado automático y monitoreo
Cloudflare: Implementación sin servidor con distribución global en el borde y cero arranques en frío

Inicio rápido

Requisitos previos

Cliente MCP compatible (Claude Desktop, Cursor, etc.)
Para desarrollo: Python 3.8 o superior, Git

Instalación

Opción 1: Extensión DXT (Recomendada)

La forma más fácil de instalar el servidor MCP de ProPublica es usando el formato de extensión DXT:

Instalar desde GitHub Releases:

Vaya a la página de versiones
Descargue el último archivo propublica-mcp-[version].dxt
Instale la extensión 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 otros clientes MCP: Siga las instrucciones de instalación DXT de su cliente o extraiga el archivo DXT a su directorio de extensiones MCP.

Opción 2: Docker (Producción)

Para implementaciones de producción o entornos contenedorizados:

Inicio rápido con 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:

Descargue el archivo de composición:

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 el entorno (opcional):

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

Inicie el servicio:

docker-compose up -d

Opción 3: Implementación en la nube

Plataforma de aplicaciones de DigitalOcean:

Haga clic en el botón "Implementar en DO" arriba
Conecte su cuenta de GitHub (si aún no está conectada)
Configure las variables de entorno (opcional - se proporcionan valores predeterminados)
Haga clic en "Implementar" - su aplicación estará en línea en minutos con una URL pública

Cloudflare Workers:

Haga clic en el botón "Implementar en Cloudflare Workers" arriba
Conecte su cuenta de GitHub y autorice Cloudflare
Configure las variables de entorno según sea necesario
Implemente - su función sin servidor estará en línea globalmente

🚀 Estrategia de implementación de producción

Las implementaciones en la nube solo se implementan desde la rama deploy, que contiene versiones estables y probadas:

Desarrollo: Todo el trabajo ocurre en la rama main

Versiones: Cuando se crean etiquetas (por ejemplo, v0.2.0), la rama deploy se actualiza automáticamente

Plataformas en la nube: DigitalOcean y Cloudflare implementan solo desde la rama deploy

Beneficios: Garantiza que solo las versiones estables y publicadas lleguen a los entornos de producción

Opción 4: Instalación local de Python (Desarrollo)

Para desarrollo y personalización:

Clone el repositorio:

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

Cree y active un entorno virtual:

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

Instale las dependencias:

pip install -r requirements.txt

Instale el paquete:

pip install -e .

Ejecute el servidor:

Para modo stdio (clientes MCP locales):

python -m propublica_mcp.server

Para modo HTTP (clientes MCP remotos):

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

Opciones disponibles:

--http: Habilitar modo de servidor HTTP para clientes MCP remotos
--host: Host al que vincular (predeterminado: 127.0.0.1)
--port: Puerto al que vincular (predeterminado: 8080)
--log-level: Establecer nivel de registro (DEBUG, INFO, WARNING, ERROR)

Uso con clientes MCP

Este servidor implementa el protocolo de transporte HTTP Streamable MCP 2025-03-26 y se puede usar con cualquier cliente MCP, incluidos Claude Desktop, Cursor y otras herramientas compatibles.

Para extensión DXT (Recomendada):

Una vez instalado como extensión DXT, el servidor se configurará automáticamente. La mayoría de los clientes MCP detectarán y cargarán la extensión automáticamente.

Configuración manual de DXT (si es necesario):

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

Para implementación en la nube (servidor MCP remoto):

DigitalOcean/Cloudflare (HTTP Streamable):

Para servidores MCP remotos de Python, necesitará usar un transporte HTTP. Agregue esto a la configuración de su cliente MCP:

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

Para instalación local (transporte stdio):

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

Para implementación con 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 (desarrollo):

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

Luego configure como servidor remoto:

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

Herramientas de API

Herramientas principales

search_nonprofits: Buscar organizaciones sin fines de lucro
get_organization: Obtener información detallada de la organización por EIN
get_organization_filings: Recuperar presentaciones del Formulario 990 para una organización

Herramientas avanzadas

analyze_nonprofit_financials: Analizar tendencias financieras a lo largo de múltiples años
search_similar_nonprofits: Encontrar organizaciones similares
export_nonprofit_data: Formatear datos para importación a CRM

Fuentes de datos

Este servidor utiliza la API de Nonprofit Explorer de ProPublica que proporciona:

Datos del Formulario 990 del IRS para organizaciones exentas de impuestos
Perfiles de organizaciones e información de contacto
Datos financieros e historial de presentaciones
Categorización NTEE y estado 501(c)

Desarrollo

Estructura del proyecto

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

El proyecto ahora admite tanto la estructura tradicional de paquetes de Python como el nuevo formato de extensión DXT. El directorio server/ contiene la estructura compatible con DXT que se empaqueta en archivos .dxt durante las versiones.

Desarrollo con Docker

Construcción de la imagen Docker

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

# Or use docker-compose
docker-compose build

Ejecución del entorno de desarrollo

# 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

Variables de entorno

El contenedor Docker admite estas variables de entorno:

LOG_LEVEL: Establecer nivel de registro (DEBUG, INFO, WARNING, ERROR)
API_RATE_LIMIT: Solicitudes por minuto (predeterminado: 60)
PROPUBLICA_API_BASE_URL: URL base de la API (rara vez necesita cambios)

Ejecución de pruebas

Pruebas locales

# Run all tests
pytest tests/ -v

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

Pruebas con 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

Construcción de extensiones DXT

El proyecto incluye empaquetado DXT automatizado a través de GitHub Actions. Los archivos DXT se construyen automáticamente y se adjuntan a las versiones.

Construcción automatizada de DXT (Recomendada)

Cree una etiqueta para activar el empaquetado DXT automatizado:

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

Esto:

Empaquetará el directorio server/ en un archivo .dxt
Creará una versión de GitHub con el archivo DXT adjunto
Construirá y publicará imágenes Docker en GitHub Container Registry

Construcción manual de DXT

Para desarrollo o pruebas:

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

Publicación en GitHub Container Registry

El proyecto incluye publicación automatizada a través de GitHub Actions, pero también puede publicar manualmente:

Requisitos previos

Token de acceso personal de GitHub con alcance packages:write

Autenticación en GitHub Container Registry:

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

Publicación automatizada (Recomendada)

Empuje a la rama main o cree una etiqueta para activar las compilaciones automatizadas:

# 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

Publicación manual

Use el script proporcionado (requiere configuración local):

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

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

Paquetes disponibles

Una vez publicados, los siguientes paquetes estarán disponibles:

Extensiones DXT:

Última: Disponible en GitHub releases
Versiones etiquetadas: propublica-mcp-v1.0.0.dxt
Descarga directa: https://github.com/asachs01/propublica-mcp/releases/latest/download/propublica-mcp.dxt

Imágenes Docker:

Última: ghcr.io/asachs01/propublica-mcp:latest
Versiones etiquetadas: ghcr.io/asachs01/propublica-mcp:v1.0.0
Compilaciones de ramas: ghcr.io/asachs01/propublica-mcp:main

Contribuciones

Siga el estilo de código existente
Agregue pruebas para nuevas características
Actualice la documentación según sea necesario
Asegúrese de que todas las pruebas pasen antes de enviar

Licencia

Licencia MIT - consulte el archivo LICENSE para obtener detalles

Soporte

Para problemas y preguntas:

Consulte la documentación
Revise los problemas existentes de GitHub
Cree un nuevo problema con información detallada