Propublica MCP

ProPublica MCP服务器

模型上下文协议（MCP）服务器，提供对ProPublica非营利组织资源管理器API的访问，使人工智能模型能够搜索和分析非营利组织的Form 990数据，用于CRM集成和前景研究。

🚨 v1.0.0中的重大更改 1.0.0版本介绍 打破变化 随着MCP 2025-03-26可流式HTTP传输的实现： - 远程部署 现在使用单个 / 端点而不是 /sse 和 /messages - MCP客户端配置 云部署已更改（请参阅下面的使用部分） - 提高兼容性 使用Claude Desktop、Cursor和其他MCP客户端 - 向后不兼容 MCP客户期待旧的SSE传输

特性

• 按名称、地点和类别搜索非营利组织
• 检索详细的组织简介和联系信息
• 访问990表格财务数据和归档历史
• 分析多年来的财务趋势
• 以CRM就绪格式导出数据
• 采用FastMCP构建，实现最佳性能

🚀 一键部署

立即将ProPublica MCP服务器部署到您首选的云平台：

数字海洋应用平台


Cloudflare员工


这两个平台都提供：

• 数字海洋：基于容器的部署，具有自动扩展和监控功能
• 云耀：具有全球边缘分布和零冷启动的无服务器部署

快速开始

先决条件

• 兼容的MCP客户端（克劳德桌面、光标等）
• 开发：Python 3.8或更高版本，Git

安装

选项1:DXT扩展（推荐）

安装ProPublica MCP服务器的最简单方法是使用DXT扩展格式：

从GitHub版本安装：

1. 转到 发布页面
2. 下载最新 propublica-mcp-[version].dxt 文件
3. 安装DXT扩展：

对于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

对于其他MCP客户端： 按照客户的DXT安装说明进行操作，或将DXT文件解压缩到MCP扩展目录中。

选项2：Docker（生产）

对于生产部署或容器化环境：

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

使用Docker Compose：

1. 下载撰写文件：

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

1. 配置环境（可选）：

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

1. 启动服务：

docker-compose up -d

选项3：云部署

DigitalOcean应用平台：

1. 点击上面的“部署到DO”按钮
2. 连接您的GitHub帐户（如果尚未连接）
3. 配置环境变量（可选-提供默认值）
4. 点击“部署”-您的应用程序将在几分钟内通过公共URL上线

Cloudflare员工：

1. 点击上面的“部署到Cloudflare Workers”按钮
2. 连接您的GitHub帐户并授权Cloudflare
3. 根据需要配置任何环境变量
4. 部署-您的无服务器功能将在全球范围内运行

🚀 生产部署策略 云部署仅从 deploy 分支，其中包含稳定的、经过测试的版本： - 发展：所有工作都发生在 main 分支 - 发布：当创建标签时（例如。， v0.2.0)，the deploy 分支会自动更新 - 云平台：DigitalOcean和Cloudflare仅从 deploy 分支 - 益处：确保只有稳定的已发布版本才能进入生产环境

选项4：本地Python安装（开发）

对于开发和定制：

1. 克隆存储库：

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

1. 创建并激活虚拟环境：

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

1. 安装依赖项：

pip install -r requirements.txt

1. 安装软件包：

pip install -e .

1. 运行服务器：

对于stdio模式（本地MCP客户端）：

python -m propublica_mcp.server

对于HTTP模式（远程MCP客户端）：

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

可用选项：

• --http：为远程MCP客户端启用HTTP服务器模式
• --host：要绑定的主机（默认值：127.0.0.1）
• --port：要绑定的端口（默认值：8080）
• --log-level：设置日志记录级别（调试、信息、警告、错误）

与MCP客户端一起使用

此服务器实现 MCP 2025-03-26可流式HTTP 传输协议，可用于任何MCP客户端，包括Claude Desktop、Cursor和其他兼容工具。

对于DXT扩展（推荐）：

一旦安装为DXT扩展，服务器将自动配置。大多数MCP客户端会自动检测并加载扩展。

手动DXT配置（如果需要）：

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

对于云部署（远程MCP服务器）：

DigitalOcean/CCloudflare（流式HTTP）：

对于远程Python MCP服务器，您需要使用HTTP传输。将此添加到MCP客户端配置中：

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

对于本地安装（stdio传输）：

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

对于Docker部署（stdio传输）：

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

对于本地HTTP服务器（开发）：

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

然后配置为远程服务器：

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

API工具

核心工具

• search_nonprofits：搜索非营利组织
• get_组织：通过EIN获取详细的组织信息
• get_organization_filings：检索组织的990表格文件

高级工具

• 非盈利金融分析：分析多年来的财务趋势
• 搜索_相似_无利润：查找类似组织
• 出口_无利润_数据：设置CRM导入的数据格式

数据源

此服务器使用 ProPublica非营利组织资源管理器API 其提供：

• IRS表格990免税组织数据
• 组织简介和联系信息
• 财务数据和归档历史
• NTEE分类和501（c）状态

发展

项目结构

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

该项目现在支持传统的Python包结构和新的DXT扩展格式。这 server/ 目录包含打包到其中的DXT兼容结构 .dxt 发布期间的文件。

Docker开发

构建Docker镜像

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

# Or use docker-compose
docker-compose build

运行开发环境

# 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

环境变量

Docker容器支持以下环境变量：

• LOG_LEVEL：设置日志记录级别（调试、信息、警告、错误）
• API_RATE_LIMIT：每分钟请求数（默认值：60）
• PROPUBLICA_API_BASE_URL：API基本URL（很少需要更改）

运行测试

局部测试

# Run all tests
pytest tests/ -v

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

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

构建DXT扩展

该项目包括通过GitHub Actions自动打包DXT。DXT文件会自动构建并附加到版本中。

自动化DXT大楼（推荐）

创建标签以触发自动DXT打包：

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

这将：

1. 打包 server/ 目录到a .dxt 文件
2. 创建附带DXT文件的GitHub版本
3. 构建Docker镜像并将其发布到GitHub容器注册表

手动DXT建筑

用于开发或测试：

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

发布到GitHub容器注册表

该项目包括通过GitHub Actions自动发布，但您也可以手动发布：

先决条件

1. GitHub个人访问令牌 随着 packages:write 范围
2. GitHub容器注册表的身份验证:

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

自动发布（推荐）

推到 main 分支或创建标签以触发自动构建：

# 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

手工出版

使用提供的脚本（需要本地设置）：

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

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

可用包

一旦发布，以下软件包将可用：

DXT扩展：

• 最新：可从以下网址获得
• 标记版本: propublica-mcp-v1.0.0.dxt
• 直接下载: https://github.com/asachs01/propublica-mcp/releases/latest/download/propublica-mcp.dxt

Docker镜像：

• 最新: ghcr.io/asachs01/propublica-mcp:latest
• 标记版本: ghcr.io/asachs01/propublica-mcp:v1.0.0
• 分支机构建设: ghcr.io/asachs01/propublica-mcp:main

贡献

1. 遵循现有代码样式
2. 为新功能添加测试
3. 根据需要更新文档
4. 提交前确保所有测试通过

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

• 检查文档
• 查看现有的GitHub问题
• 创建包含详细信息的新问题