Financial Reports MCP Server

🎬 Demo

An MCP (Model Context Protocol) server for accessing the Financial Reports API, providing tools and resources to access company financial filings, industry classifications, and related data.

Features

• Search for companies by name, country, or sector
• Get detailed company information
• Access latest financial filings
• Look up industry classifications
• Get filing details and content

Prerequisites

• Python 3.11+
• Docker (recommended)
• FastMCP (if running locally)
• dotenv for environment variable management (if running locally)

Note: The server now uses only the real Financial Reports API. All mock API logic and configuration has been removed for simplicity and reliability.

🚀 Getting Started

There are multiple ways to run this MCP server. Choose one of the following:

Option 1: Docker (Recommended)

Docker is the recommended way to run the MCP server for reproducibility, isolation, and ease of use.

# Build (once)
docker build -t financial-reports-mcp .

# Run
docker run --rm -i \
  -e API_KEY=your_api_key_here \
  -e API_BASE_URL=https://api.financialreports.eu/ \
  -e MCP_TRANSPORT=stdio \
  financial-reports-mcp:latest

For Docker Compose users:

# Copy and configure .env
echo "Copy .env.example to .env and fill in secrets"
cp .env.example .env
# Start services
docker-compose up

For Claude Desktop, use the following configuration. Pass secrets as -e arguments in args for maximum compatibility and security:

{
  "mcpServers": {
    "financial-reports": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "API_KEY=your_api_key_here",
        "-e", "API_BASE_URL=https://api.financialreports.eu/",
        "-e", "MCP_TRANSPORT=stdio",
        "financial-reports-mcp:latest"
      ]
    }
  }
}

Why? Passing secrets as -e arguments in args guarantees Docker always receives them, regardless of how the client implements environment variable support. This is the most robust and portable approach for Claude Desktop and similar clients.

Option 2: Smithery CLI (for Claude)

Use the Smithery CLI to install and run the server in Claude:

npx -y @smithery/cli@latest install \
  @itisaevalex/financial-reports-mcp-server \
  --client claude \
  --key smithery_api_key

Option 3: Local Python (development/testing)

1. Install dependencies:

python -m venv venv           # Create venv
venv\Scripts\activate        # Activate on Windows
pip install -r requirements.txt

2. Run the server:

python -m src.financial_reports_mcp
# or with uv
uv run src/financial_reports_mcp.py

Tip: If you use uv, it automatically loads .env from the project root.

Examples

All example scripts and configs are now located in the examples/ directory, e.g.:

• examples/test_server.py — Run the full MCP test suite
• examples/docker_claude_config.json — Example Claude Desktop config for Docker
• examples/uvx_claude_config.json — Example Claude Desktop config for uv
• examples/python_client_example.py — Example Python client usage

Run the test suite:

python examples/test_server.py

Configuration

Create a .env file in the root directory with the following variables:

API_KEY=your_api_key_here
API_BASE_URL=https://api.financialreports.eu/
MCP_TRANSPORT=stdio

Project Structure

• src/ — Source code directory
  • financial_reports_mcp.py — MCP server main entrypoint (all tools/resources defined here)
  • api_client.py — API client factory
  • real_api/real_client.py — Real API client implementation
• .env - Environment variables (not in git)
• requirements.txt - Project dependencies
• Dockerfile & docker-compose.yml - Docker configuration
• setup.py - Package install

... View full README on GitHub