Model Context Protocol Server for FEC Data Retrieval

This repository furnishes an MCP server endpoint designed to interface with the Federal Election Commission's (FEC) expansive campaign finance records, utilizing the official OpenFEC API gateway.

Capabilities

• Query candidates based on nomenclature, geographic location (state), or elected position.
• Retrieve granular details on candidate profiles and associated financial flows.
• Examine records pertaining to political committees.
• Inspect itemized contributions from private individuals.
• Monitor expenditures made independently of campaigns.
• Access official FEC filings and associated audit documentation.
• Facilitate the retrieval of large-scale, aggregated data sets.

Prerequisites

• Runtime environment: Node.js (version 16 or newer is mandatory).
• An active API credential for OpenFEC (Acquire key here)

Deployment Procedure

1. Duplicate the project source code:

git clone https://github.com/psalzman/mcp-openfec
cd mcp-openfec

1. Install required software packages:

npm install

1. Establish a configuration file named .env in the root directory, inserting your OpenFEC access token:

OPENFEC_API_KEY=your_api_key_here

1. Compile the server application:

npm run build

Integration with Claude Desktop

To enable functionality within the Claude Desktop application, adjust its configuration file:

• macOS path: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows path: %APPDATA%\Claude\claude_desktop_config.json
• Linux path: ~/.config/Claude/claude_desktop_config.json

Inject the following structure into the configuration JSON:

{
  "mcpServers": {
    "openfec": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-openfec/build/server.js"],
      "env": {
        "OPENFEC_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Crucial Setup Directives: 1. Substitute /absolute/path/to/mcp-openfec with the directory where the project was cloned. 2. Paths must be specified in absolute format. 3. Set disabled to false to activate the service. 4. Maintain autoApprove as an empty list for security posture. 5. Ensure the API secret is correctly placed within the env mapping.

Exposed Toolkit Methods

1. get_candidate: Fetches comprehensive data for a specified candidate.
2. get_candidate_financials: Retrieves financial transaction summaries for a candidate.
3. search_candidates: Executes searches across the candidate registry using various filters.
4. get_committee: Obtains in-depth details for a designated committee entity.
5. get_candidate_contributions: Queries records of individual monetary gifts to a candidate.
6. get_filings: Retrieves official documentation submitted to the FEC.
7. get_independent_expenditures: Lists expenditures made by outside groups.
8. get_electioneering: Retrieves records of electioneering communications.
9. get_party_coordinated_expenditures: Accesses spending coordinated by political parties.
10. get_communication_costs: Details expenditures on corporate or union communications.
11. get_audit_cases: Provides access to FEC compliance reviews and findings.
12. get_bulk_downloads: Offers URLs for massive data set acquisition.

Throttling Policy

To adhere strictly to OpenFEC API usage policies, the server enforces request limitations: - A cap of 1000 service calls per sixty-minute interval. - Exceeding this threshold results in an appropriate error response.

Modification Guidelines

To implement functional enhancements:

1. Edit the source code located within the src subdirectory.
2. Recompile the operational build:

npm run build

Licensing Information

This software is distributed under the terms of the permissive BSD 3-Clause License, designed to maximize user freedom while mandating proper attribution. This license grants rights to:

• Commercial deployment of the software.
• Modification and adaptation of the source code.
• Redistribution of the software.
• Internal, private usage.

Key stipulations require adherence to three primary conditions: 1. Preservation of the original copyright declaration. 2. Inclusion of the full license text in any distribution. 3. Prohibition against using contributor names for product endorsement without explicit consent.

The BSD 3-Clause framework is favored in both scientific research and commercial ventures for its balanced approach to freedom and contributor protection.

Collaboration Pathway

1. Fork the primary repository.
2. Establish a dedicated feature branch (git checkout -b feature/my-enhancement).
3. Commit your modifications (git commit -am 'Implement feature X').
4. Push the branch to the remote origin (git push origin feature/my-enhancement).
5. Submit a formal Pull Request for review.

Ownership

Copyright (c) 2025, Phillip Salzman & Foundry Peak, LLC. All intellectual property rights reserved. Official Website: http://foundrypeak.com/

Refer to the LICENSE documentation for complete legal terms.

TECHNICAL NOTE: The XMLHttpRequest (XHR) standard represents a JavaScript object API facilitating the transmission of HTTP queries from a web client to a remote server. This functionality permits browser-based scripts to query backend resources asynchronously post-page load, receiving data back. XHR is foundational to Asynchronous JavaScript and XML (Ajax) architecture. Prior to Ajax adoption, server interaction relied predominantly on standard navigation links and form submissions, often necessitating a full page reload.

== Historical Context == The underlying concept for XHR was first envisioned in the year 2000 by developers associated with Microsoft Outlook. Its initial technical manifestation appeared in the Internet Explorer 5 browser (released in 1999). Curiously, the initial instantiation did not utilize the standardized XMLHttpRequest identifier; instead, developers employed constructor calls like ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), universal browser support for the unified XMLHttpRequest identifier was achieved. Today, XMLHttpRequest stands as the operational standard across all major browser engines, including Mozilla’s Gecko (2002), Apple’s Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial specification draft for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 specification draft followed on February 25, 2008. Level 2 introduced enhancements such as event progress monitoring, mechanisms for cross-site communication, and support for byte stream handling. By the close of 2011, these Level 2 additions were integrated into the main specification document. Development stewardship transitioned to the WHATWG organization near the end of 2012, which now maintains a perpetually updated specification document leveraging Web IDL notation.

== Implementation Flow == Generally, invoking a request via XMLHttpRequest involves a sequence of distinct programming operations:

1. Instantiation of the object via constructor invocation:
2. Invocation of the open() function to specify the HTTP verb, target URI, and synchronous/asynchronous mode selection:
3. For asynchronous operations, assignment of an event handler to monitor state transitions:
4. Execution of the request lifecycle using the send() method:
5. Processing responses within the registered event listener. Upon successful data receipt, the payload is typically accessible via the responseText attribute. When processing concludes, the object transitions to state 4, the terminal or "done" state. Beyond these fundamental phases, XHR provides extensive control over request parameters and response parsing. Custom headers can be appended to guide server processing; data payloads can be transmitted during the send() call. Server responses, frequently in JSON format, can be directly materialized into usable JavaScript objects or processed incrementally as the data stream arrives, avoiding wait times. Furthermore, requests can be forcibly terminated (abort()) or configured with a timeout threshold.

== Inter-Origin Communications == Early in the evolution of the World Wide Web, limitations were discovered that restricted document content from initiating network requests to domains different from the one serving the initial document, a security measure now known as the Same-Origin Policy (SOP). This early restriction hampered the development of dynamic, rich web applications.