Author: Reinaldo Chaves ([email protected])

GitHub Python License FastMCP OpenFEC

Leia isto em Português

An MCP server that connects the OpenFEC API to AI assistants, allowing you to investigate US federal campaign finance through natural conversations.

Designed for data journalists, researchers, and citizens who need to explore complex Federal Election Commission (FEC) data without directly knowing the API.

---

Table of Contents

• What is MCP?
• What does this project do?
• Architecture
• Available Tools
• Installation
• Configuration
• Usage Examples
• Development and Tests
• Security

---

What is MCP?

MCP (Model Context Protocol) is an open standard that enables AI assistants to communicate with external systems — databases, APIs, files, services — securely and uniformly.

The three types of MCP capabilities

Type	What it is	Example in this project
Tools	Functions the AI can call to fetch or manipulate data	search_candidates(), get_top_donors()
Resources	Static or contextual data that is always available	FEC codes tables, notable IDs, Glossary
Prompts	Workflow templates guiding complex investigations	investigate_candidate(), follow_the_money()

---

What does this project do?

This project exposes the OpenFEC API as an MCP server. The result: you can investigate political financing just by conversing with an LLM.

Key Capabilities

• Candidate Search: Find any federal candidate by name, state, party, or office.
• Financial Analysis: Totals raised, spent, debts, and Cash on Hand.
• Donor Tracking: Identify the top financiers of a campaign and their employers.
• Geo-analysis: See from which states a candidate's money comes.
• Super PACs and Independent Expenditures: Monitor outside groups spending to support or attack candidates.
• Official Reports: Access filings submitted to the FEC by campaigns and committees.
• Guided Investigation: Ready-to-use workflows for journalistic investigations.

🔍 Methodological Note (OSINT and Data Architecture)

The FEC API separates "Candidate Totals" (the primary endpoint of the official committee) from the money housed in Political Action Committees (PACs). The fec_mcp was designed strictly for the "Zero Hallucination" principle. It exposes data exactly as the government bureaucracy classifies it. In OSINT investigations, it is up to the AI agent or journalist to use search_candidates to list all Principal Authorized Committees and PACs attached to a politician and query their finances individually.

Multi-language Support (i18n)

The server supports internationalization. The default language for responses and tips is English. You can change this by setting the FEC_MCP_LANG environment variable (e.g., FEC_MCP_LANG=pt-br).

---

Architecture

fec-mcp-server/
├── README.md                    # Main documentation in English
├── README.pt-br.md              # Main documentation in Portuguese
├── .env.example                 # Example environment variables (API keys, language)
├── pyproject.toml               # Project configuration and modern Python dependencies
├── requirements.txt             # List of dependencies for simple installation via pip
├── start_server.py              # Entry point: adds src/ to path and starts the MCP server
├── src/fec_mcp/
│   ├── main.py                  # Imports all modules to register them in FastMCP
│   ├── server.py                # Creates the central `mcp = FastMCP(...)` instance
│   ├── context.py               # Singleton `fec`: shared instance of FECClient
│   ├── client.py                # Active FECClient: HTTP requests, retry/backoff, timeouts
│   ├── i18n.py                  # Internationalization system (loads text from /locales)
│   ├── logging_config.py        # Logging configuration and verbosity levels
│   ├── models.py                # Pydantic data models for validating API responses
│   ├── tools/                   # MCP Tools (@mcp.tool)
│   │   ├── candidates.py        # search_candidates, get_candidate_finances
│   │   ├── contributions.py     # search_contributions, get_top_donors, get_contributions_by_state
│   │   ├── expenses.py          # get_campaign_expenditures, get_independent_expenditures
│   │   ├── filings.py           # get_campaign_filings for financial reports
│   │   ├── search.py            # search_pacs for finding political action committees
│   │   └── meta.py              # fec_help, suggest_investigation
│   ├── resources/               # MCP Resources (@mcp.resource)
│   │   └── reference.py         # FEC codes, notable IDs, glossary, API info
│   ├── prompts/                 # MCP Prompts (@mcp.prompt)
│   │   └── investigation.py     # investigate_candidate, follow_the_money, compare_candidates
│   ├── data/                    # Static JSON files used by tools
│   │   ├── glossary.json        # FEC glossary terms
│   │   ├── help.json            # Documentation and examples by topic for fec_help
│   │   └── investigations.json  # Journalism investigation pitches
│   └── locales/                 # Translation files
│       ├── en.json              # English translations
│       └── pt.json              # Portuguese translations
└── tests/
    └── test_server.py           # Automated tests for the client and endpoints using pytest and respx

---

Available Tools

Tools

• search_candidates: Search for federal candidates.
• get_candidate_finances: Get financial totals for a candidate.
• search_contributions: Search for individual donations (Schedule A).
• get_top_donors: List the top donors to a committee.
• get_contributions_by_state: Aggregate donations by state.
• get_campaign_expenditures: List a campaign's expenditures (Schedule B).
• get_independent_expenditures: Search for independent expenditures by Super PACs.
• get_candidate_filings / get_committee_filings: List financial reports submitted to the FEC.
• search_pacs: Search for PACs and Super PACs by name.
• fec_help: Internal documentation for the tools.
• suggest_investigation: Journalistic pitch suggestions based on FEC data.

Resources

URI	Content
fec://reference/codes	Party codes, offices, committee types, filing types, donation limits
fec://reference/notable_ids	IDs of presidential candidates, national committees, relevant Super PACs
fec://reference/api_info	Data coverage, rate limits, usage tips
fec://reference/glossary	Glossary of FEC terminology (e.g., PAC, Schedule A, Cash on Hand)

Prompts

• investigate_candidate(candidate_name): Step-by-step workflow for a complete financial investigation of a candidate.
• follow_the_money(company_name): Tracks the political influence of a company.
• compare_candidates(candidate1, candidate2): Side-by-side comparison of two candidates.

---

Installation

Prerequisites

• Python 3.10+
• FEC API Key: Free at api.data.gov/signup

Steps

git clone https://github.com/your-username/fec-mcp-server.git
cd fec-mcp-server
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
echo "FEC_API_KEY=your_key_here" > .env

---

Usage Examples

Investigate a candidate

"Investigate the campaign finances of Kamala Harris in 2024"

The LLM will automatically execute:

1. search_candidates(name="Kamala Harris", election_year=2024)
2. get_candidate_finances(candidate_id="P00009423")
3. get_top_donors(committee_id="C00703975")

Compare candidates

"Compare the finances of Trump and Biden for 2024"

The prompt compare_candidates generates a complete table with all metrics side by side.

---

Known Limitations

• Federal data only: State and local elections are not in the FEC.
• Dark money: Donations to 501(c)(4) are not disclosed to the FEC.
• Latency: Individual donation endpoints (schedule_a) can be slow.
• Rate limit: 1,000 requests/hour with the free API key.

Security

This server runs locally on your machine and makes read-only requests to the public OpenFEC API. It handles no user credentials or PII.

Key practices:

• Store your API key in .env only — never commit it (.env is in .gitignore)
• API key is automatically masked in all log output (SecretFilter)
• Logs rotate at 5 MB and are excluded from version control
• Input filenames loaded from disk are restricted to an explicit allowlist

For the full threat model, Skill Vetter compatibility declaration, dependency audit instructions, and how to report vulnerabilities, see SECURITY.md.

# Audit dependencies for known CVEs
pip-audit

# Static security analysis
bandit -r src/

# Run security-focused tests
pytest tests/test_security.py -v

---

External Resources

• OpenFEC API — Documentation
• FEC — Official Website
• OpenSecrets
• FastMCP — Documentation
• MCP — Protocol Specification