A Model Context Protocol (MCP) server for accessing OParl parliamentary data APIs
📚 Documentation • 🚀 Quick Start • 🏛️ OParl API • 🔧 Configuration • 🐳 Docker
This project is currently in development and requires additional validation and testing. While the core functionality is implemented, it has not been thoroughly tested in production environments. Please use with caution and report any issues you encounter.
The OParl MCP Server provides AI models and applications with seamless access to OParl parliamentary data APIs through the Model Context Protocol. It enables natural language queries and structured access to parliamentary information systems across multiple implementations.
- 🔌 MCP Integration: Full Model Context Protocol compliance
- 🏛️ OParl 1.1 Support: Complete support for all OParl object types
- 🌐 Multi-Implementation: Works with various OParl implementations
- 🔐 Authentication: Flexible API key and Bearer token support
- 📊 Rich Data Access: Parliamentary meetings, documents, organizations, and more
- 🔍 Advanced Search: Query parameters and filtering capabilities
- 🐳 Docker Ready: Containerized deployment with Docker Compose
- 🧪 Comprehensive Testing: Unit tests and integration tests included
- 📚 Extensive Documentation: Complete API reference and usage guides
The server provides access to all standard OParl 1.1 object types:
| Object Type | Description | Key Properties |
|---|---|---|
| System | Root system information | oparlVersion, body, created |
| Body | Parliamentary bodies | name, shortName, organization |
| Organization | Political parties & groups | name, shortName, member |
| Person | Representatives & officials | name, givenName, familyName |
| Meeting | Parliamentary sessions | name, start, end, location |
| AgendaItem | Meeting topics | name, meeting, order |
| Paper | Documents & resolutions | name, reference, date |
| Consultation | Public consultations | name, paper, start, end |
| File | Attachments & media | name, mimeType, accessUrl |
| Location | Meeting venues | name, geojson, postalCode |
- Python 3.11 or higher
- pip (Python package manager)
-
Clone the repository
git clone https://github.com/jtwolfe/oparl-mcp-server.git cd oparl-mcp-server -
Create a virtual environment
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install dependencies
pip install -r requirements.txt
-
Run the server
python -m oparl_mcp.server
For development, install additional dependencies:
pip install -r requirements-dev.txtThe server can be configured using environment variables or programmatically:
export OPARL_BASE_URL="https://api.oparl.org"
export OPARL_API_KEY="your-api-key" # Optional
export OPARL_TIMEOUT="30.0"
export OPARL_LOG_LEVEL="INFO"
export OPARL_SERVER_NAME="OParl MCP Server"from oparl_mcp import OParlConfig, OParlMCPServer
# Create configuration
config = OParlConfig(
base_url="https://oparl.muenchen.de",
api_key="your-munich-api-key",
timeout=60.0,
server_name="Munich OParl Server"
)
# Create and run server
server = OParlMCPServer(config)
server.run()The server works with various OParl implementations:
| Implementation | URL | Description |
|---|---|---|
| Generic OParl API | https://api.oparl.org |
Standard OParl implementation |
| Munich City Council | https://oparl.muenchen.de |
Munich parliamentary data |
| Cologne City Council | https://oparl.koeln.de |
Cologne parliamentary data |
| Hamburg Parliament | https://oparl.hamburg.de |
Hamburg parliamentary data |
Each implementation may have different:
- Authentication requirements
- Available data
- API endpoints
- Rate limits
-
Create environment file
cp .env.example .env # Edit .env with your configuration -
Run with Docker Compose
docker-compose -f docker/docker-compose.yml up -d
# Build the image
docker build -f docker/Dockerfile -t oparl-mcp-server .
# Run the container
docker run -p 8000:8000 \
-e OPARL_BASE_URL=https://api.oparl.org \
-e OPARL_API_KEY=your-key \
oparl-mcp-serverfrom mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main():
async with stdio_client(StdioServerParameters(
command="python",
args=["-m", "oparl_mcp.server"]
)) as (read, write):
async with ClientSession(read, write) as session:
# List all meetings
meetings = await session.list_resources()
print(f"Found {len(meetings)} resources")
# Get specific meeting
meeting = await session.read_resource("oparl_meeting_123")
print(f"Meeting: {meeting['name']}")from oparl_mcp import OParlMCPServer, OParlConfig
# Custom configuration for Munich
config = OParlConfig(
base_url="https://oparl.muenchen.de",
api_key="your-munich-api-key",
timeout=45.0,
server_name="Munich OParl MCP Server"
)
server = OParlMCPServer(config)
info = server.get_server_info()
print(f"Server: {info['name']}")
print(f"Features: {info['features']}")Run the comprehensive test suite:
# Run all tests
pytest
# Run with coverage
pytest --cov=oparl_mcp --cov-report=html
# Run specific test file
pytest tests/test_server.py
# Run integration tests
python test_integration.pyComprehensive documentation is available at https://jtwolfe.github.io/oparl-mcp-server/:
- Getting Started - Quick setup and basic usage
- OParl API Guide - Complete OParl API reference
- FastMCP Integration - Technical integration details
- Architecture - System design and data flow
- API Reference - Complete API documentation
- Contributing - Development and contribution guide
- System Information: Root system data and metadata
- Body Collections: Lists of parliamentary bodies
- Meeting Schedules: Upcoming and past meetings
- Document Collections: Papers and reports
- Person Profiles: Elected officials and staff
- Individual Objects: Specific meetings, people, papers, etc.
- Parameterized Access: Dynamic resource access with IDs
- Structured Data: Consistent data format across all objects
- Search Operations: Find specific data across the system
- Filter Operations: Filter data by various criteria
- Export Operations: Export data in different formats
The server uses FastMCP to transform the OParl API into MCP-compatible components:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI Model │ │ MCP Client │ │ MCP Server │
│ │◄──►│ │◄──►│ (FastMCP) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ OParl API │
│ (HTTP/REST) │
└─────────────────┘
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/new-feature - Install development dependencies:
pip install -r requirements-dev.txt - Make your changes
- Add tests for new functionality
- Run the test suite:
pytest - Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
- OParl Initiative for the standardized parliamentary data API
- FastMCP for the excellent MCP framework
- Model Context Protocol for the AI integration standard
- The open-source community for inspiration and support
- Documentation: https://jtwolfe.github.io/oparl-mcp-server/
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- OParl Specification - Official OParl documentation
- FastMCP Framework - MCP server generation framework
- Model Context Protocol - AI integration standard
Made with ❤️ for open government and AI accessibility