bernardocaldas/mollie-mcp-server

Mollie MCP Server

A FastMCP server that provides access to Mollie Payments API through the Model Context Protocol (MCP).

Features

• Token-based Authentication: Uses Mollie API tokens passed directly in tool calls
• Async Mollie SDK: Built with mollie-api-python-alpha for modern async support
• MCP Protocol: Exposes Mollie functionality as MCP tools for LLM integration
• Docker Ready: Containerized with uv for fast dependency management

Requirements

• Python 3.12+
• Valid Mollie API token (test or live)

Installation

Using uv (recommended)

uv pip install -r requirements.lock

Using pip

pip install -r requirements.lock

Usage

Running the Server

python -m app.server

The server runs using STDIO transport by default, suitable for MCP protocol communication.

Available Tools

validate_mollie_token

Validates a Mollie API token format and creates a client connection.

Parameters:

• token (str): Mollie API token (format: access_test_* or access_live_*)

Returns:

{
  "valid": true,
  "message": "Token is valid and client created successfully"
}

get_mollie_client_info

Returns information about the Mollie client setup.

Parameters:

• token (str): Mollie API token

Returns:

{
  "status": "connected",
  "sdk_version": "mollie-api-python-alpha", 
  "client_type": "async_capable"
}

Development

Testing

Quick Start

# Run all tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest --cov=app --cov-report=html

Integration Testing

For tests that connect to the real Mollie API, you need to set a token:

export MOLLIE_TEST_TOKEN="access_BD8nEv87BDKRxEN87efDSHdFPBqTdSKSwwsdRb2E"
python -m pytest tests/test_mollie_integration.py -v -s

📖 See for detailed testing instructions and troubleshooting.

FastMCP Client Testing

The project includes examples of using FastMCP's client capabilities for in-memory testing:

# Run the FastMCP client demo
python examples/fastmcp_client_demo.py

import asyncio
from fastmcp import Client
from app.server import mcp

async def test_with_client():
    # Connect directly to server instance (no network/processes needed)
    async with Client(mcp) as client:
        # List available tools
        tools = await client.list_tools()
        print(f"Found {len(tools)} tools")
        
        # Execute tools
        result = await client.call_tool("validate_mollie_token", {
            "token": "access_test_example123"
        })
        print(f"Tool executed, result type: {type(result)}")

asyncio.run(test_with_client())

Benefits of FastMCP Client Testing:

• ✅ In-Memory: No separate processes or network calls
• ✅ Fast: Direct function calls, minimal overhead
• ✅ Complete: Tests full MCP request/response cycle
• ✅ Concurrent: Easy to test multiple connections
• ✅ Schema Validation: Verify tool schemas automatically
• ✅ No Parsing Complexity: Focus on functionality, not response formats

Linting

ruff check .
ruff format .

Docker

Build the image:

docker build -f docker/Dockerfile -t mollie-mcp-server .

Run the container:

docker run -i mollie-mcp-server

Architecture

This implementation follows the "Token-Pass-Through" pattern where:

1. No token storage: Tokens are passed with each tool call
2. No authentication middleware: Token validation happens per-tool
3. Simple FastMCP setup: Uses decorator-based tool registration
4. Async-ready: Built for the modern async Mollie SDK

Requirements Compliance

This implementation satisfies the core requirements:

• ✅ F-1: Token validation using regex pattern access_(live|test)_[A-Za-z0-9]+
• ✅ F-2: Manifest exposure through FastMCP (automatic)
• ✅ F-3: Uses mollie-api-python-alpha async SDK
• ✅ F-4: Ready for streaming implementation (foundation in place)
• ✅ F-5: Rate limiting can be added at transport level

License

MIT License