Metadata-Version: 2.4
Name: elections_canada_mcp_server
Version: 0.1.1
Summary: MCP server for Elections Canada data
Author: Rohan Sampath
License-Expression: MIT
Project-URL: Homepage, https://github.com/ThreeFortyThree-Canada/elections-canada-mcp-server
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: fastapi==0.110.0
Requires-Dist: uvicorn>=0.21.1
Requires-Dist: pydantic>=1.10.7
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# Elections Canada MCP Server

This is a Model Context Protocol (MCP) server that provides access to Canadian federal election data. It currently supports results from the 2021 election, redistributed to the 2023 riding boundaries. Future updates will include past elections, census demographics, and real-time projections.

Brought to you by [ThreeFortyThree](https://threefortythree.ca), this server powers [ThreeFortyThree Chat](https://threefortythree.ca/chat) and is available for use with local models via Claude Desktop.

---

## 🛠 Setup

### Installation (via PyPI)

```bash
uv pip install elections-canada-mcp-server
```

To install development dependencies:

```bash
uv pip install 'elections-canada-mcp-server[dev]'
```

---

### Usage with Claude Desktop

1. Make sure the server is installed:

```bash
uv pip install elections-canada-mcp-server
```

2. Open your `claude_desktop_config.json` and add the following block:

```json
{
  "elections_canada_data": {
    "command": "uv",
    "args": ["run", "elections-canada-mcp"]
  }
}
```

3. Restart Claude Desktop.

4. Now you can ask Claude questions like:
   - "What were the 2021 election results in Toronto Centre?"
   - "Which ridings were closest for the NDP?"
   - "Show me the highest-margin wins for the Conservatives in 2021."

---

### Local Development

To test the server using MCP Inspector:

```bash
mcp dev elections_canada_mcp_server/server.py
```

This opens a web UI to test the server locally.

---

## 🧰 Tools

| Tool | Description | Input | Returns |
|------|-------------|-------|---------|
| `search_ridings` | Search ridings by name (accent-insensitive) | `search_term: str` | List of matching ridings |
| `get_party_votes` | Get vote share in a riding (optionally by party) | `riding_code: str, party_code: str (optional)` | Votes and percentage |
| `get_winning_party` | Get the winning party in a riding | `riding_code: str` | Winning party |
| `summarize_province_results` | Province-wide summary of votes/seats | `province_name_or_code: str` | Party results |
| `summarize_national_results` | Canada-wide election summary | — | National party results |
| `find_closest_ridings` | Find most competitive ridings | `num_results: int, party: str (optional)` | Closest margins |
| `best_and_worst_results` | Best/worst ridings for a party | `party: str, num_entries: int` | 4-category performance summary |

---

## 📚 Resources

| Resource | URI |
|----------|-----|
| All ridings | `elections-canada://ridings` |
| Single riding | `elections-canada://riding/{riding_code}` |
| Province | `elections-canada://province/{province_code}` |

---

## 📌 Province Codes

AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT

## 📌 Party Codes

LPC, CPC, NDP, BQ, GPC, PPC

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).

© ThreeFortyThree Canada – [threefortythree.ca](https://threefortythree.ca)
