Skip to main content
Glama

OParl MCP Server

by jtwolfe
GitHub
Python
Apache 2.0
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

OParl MCP Server

A Model Context Protocol (MCP) server for accessing OParl parliamentary data APIs

GitHub stars GitHub forks GitHub issues GitHub license Python 3.11+ MCP Compatible

📚 Documentation • 🚀 Quick Start • 🏛️ OParl API • 🔧 Configuration • 🐳 Docker

⚠️ Project Status

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.

🎯 Overview

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.

✨ Features

  • 🔌 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

🏛️ OParl API

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

🚀 Quick Start

Prerequisites

  • Python 3.11 or higher

  • pip (Python package manager)

Installation

  1. Clone the repository

    git clone https://github.com/jtwolfe/oparl-mcp-server.git cd oparl-mcp-server

  2. Create a virtual environment

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

  3. Install dependencies

    pip install -r requirements.txt

  4. Run the server

    python -m oparl_mcp.server

Development Setup

For development, install additional dependencies:

pip install -r requirements-dev.txt

⚙️ Configuration

The server can be configured using environment variables or programmatically:

Environment Variables

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"

Programmatic Configuration

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()

🌍 OParl Implementations

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

🐳 Docker

Using Docker Compose

  1. Create environment file

    cp .env.example .env # Edit .env with your configuration

  2. Run with Docker Compose

    docker-compose -f docker/docker-compose.yml up -d

Using Docker directly

# 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-server

📖 Usage Examples

Basic MCP Client Usage

from 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']}")

Advanced Configuration

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']}")

🧪 Testing

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.py

📚 Documentation

Comprehensive documentation is available at https://jtwolfe.github.io/oparl-mcp-server/:

🔧 MCP Components

Resources

  • 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

Resource Templates

  • Individual Objects: Specific meetings, people, papers, etc.

  • Parameterized Access: Dynamic resource access with IDs

  • Structured Data: Consistent data format across all objects

Tools

  • Search Operations: Find specific data across the system

  • Filter Operations: Filter data by various criteria

  • Export Operations: Export data in different formats

🏗️ Architecture

The server uses FastMCP to transform the OParl API into MCP-compatible components:

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ AI Model │ │ MCP Client │ │ MCP Server │ │ │◄──►│ │◄──►│ (FastMCP) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ OParl API │ │ (HTTP/REST) │ └─────────────────┘

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/new-feature

  3. Install development dependencies: pip install -r requirements-dev.txt

  4. Make your changes

  5. Add tests for new functionality

  6. Run the test suite: pytest

  7. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

📞 Support

🔗 Related Projects

Made with ❤️ for open government and AI accessibility

GitHub stars GitHub forks

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Provides AI models with seamless access to OParl parliamentary data APIs through the Model Context Protocol. Enables natural language queries for parliamentary meetings, documents, organizations, representatives, and other government data across multiple OParl implementations.

  1. ⚠️ Project Status
    1. 🎯 Overview
      1. ✨ Features
        1. 🏛️ OParl API
          1. 🚀 Quick Start
            1. Prerequisites
            2. Installation
            3. Development Setup
          2. ⚙️ Configuration
            1. Environment Variables
            2. Programmatic Configuration
          3. 🌍 OParl Implementations
            1. 🐳 Docker
              1. Using Docker Compose
              2. Using Docker directly
            2. 📖 Usage Examples
              1. Basic MCP Client Usage
              2. Advanced Configuration
            3. 🧪 Testing
              1. 📚 Documentation
                1. 🔧 MCP Components
                  1. Resources
                  2. Resource Templates
                  3. Tools
                2. 🏗️ Architecture
                  1. 🤝 Contributing
                    1. Development Setup
                  2. 📄 License
                    1. 🙏 Acknowledgments
                      1. 📞 Support
                        1. 🔗 Related Projects

                          New MCP Servers

                          MCP directory API

                          We provide all the information about MCP servers via our MCP API.

                          curl -X GET 'https://glama.ai/api/mcp/v1/servers/jtwolfe/oparl-mcp-server'

                          If you have feedback or need assistance with the MCP directory API, please join our Discord server