Corporate Financial Data Hub Service

🎬 Demonstration

This is an MCP (Model Context Protocol) endpoint designed to interface with the Financial Reports API, furnishing the necessary utilities and data constructs for accessing organizational financial disclosures, sector classifications, and associated metadata.

Core Capabilities

• Query entities via legal name, geographical location, or economic sector
• Fetch granular entity data
• Access the most recent regulatory filings
• Resolve industry classifications (e.g., GICS structure)
• Retrieve specific filing metadata and content bodies

Prerequisites for Operation

• Execution environment requires Python version 3.11 or newer
• Containerization via Docker is strongly suggested
• Dependency on FastMCP (for localized deployments)
• Utilization of dotenv for managing environmental configuration variables (local use case)

Notice: This server instance exclusively leverages the production Financial Reports API. All previous simulation logic and mock configurations have been purged to enhance simplicity and operational dependability.

🚀 Initialization Procedures

Select one of the deployment modalities outlined below:

Method 1: Containerization via Docker (Recommended)

Docker offers superior deployment reproducibility, operational isolation, and ease of execution.

bash

Initial build process (execute once)

docker build -t financial-reports-mcp .

Launch command

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 users employing Docker Compose:

bash

Duplicate and configure the environment file

echo "Copy .env.example to .env and fill in secrets" cp .env.example .env

Initiate required services

docker-compose up

For utilization within the Claude Desktop environment, the subsequent configuration structure is advised. Injecting sensitive credentials via -e arguments within the args array maximizes compatibility and security posture:

{ "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" ] } } }

Rationale: Providing secrets directly via -e flags in the args parameter ensures that the Docker runtime environment persistently receives them, irrespective of the client's implementation nuances for environment variable handling. This constitutes the most resilient and portable configuration pattern for deployment on Claude Desktop and analogous client platforms.

Method 2: Smithery CLI (For Claude Integration)

Employ the Smithery command-line utility to install and activate the server within the Claude ecosystem:

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

Method 3: Local Python Execution (Dev/Testing Focus)

1. Dependency acquisition: bash python -m venv venv # Virtual environment creation venv\Scripts\activate # Activation on Windows systems pip install -r requirements.txt

2. Server activation: bash python -m src.financial_reports_mcp

Alternatively, using the uv package manager

uv run src/financial_reports_mcp.py

Guidance: When leveraging uv, environment variables stored in the root .env file are automatically sourced.

Illustrative Use Cases

All demonstration scripts and configuration artifacts are now organized within the examples/ subdirectory, for instance:

• examples/test_server.py — Executes the comprehensive MCP verification sequence
• examples/docker_claude_config.json — Sample configuration file for Claude Desktop utilizing Docker
• examples/uvx_claude_config.json — Sample configuration file for Claude Desktop utilizing uv
• examples/python_client_example.py — Demonstrative implementation of Python client interaction

Execute the integrated verification routine via: bash python examples/test_server.py

Configuration Parameters

Establish a .env file in the primary directory structure, defining the subsequent parameters:

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

Project Architecture Overview

• src/ — Primary source code repository
• financial_reports_mcp.py — Main execution module for the MCP server (where all functional tools are declared)
• api_client.py — Factory for constructing API interaction modules
• real_api/real_client.py — The actual implementation logic for the live API client
• .env - Runtime configuration secrets (excluded from version control)
• requirements.txt - Definition of project dependencies
• Dockerfile & docker-compose.yml - Artifacts for container orchestration
• setup.py - Module packaging and installation metadata
• install.py - Utility script supporting Claude Desktop installation flows
• examples/ - Repository for sample scripts and configurations
• scripts/ - Assorted installation utility scripts

Accessible Functionality (Tools)

• get_filing_type(filing_type_id) — Retrieves exhaustive metadata for a filing type, identified by its unique ID
• list_industries(industry_group, page, page_size, search) — Enumerates all extant GICS industry classifications
• get_industry(industry_id) — Fetches detailed specifications for a given GICS industry identifier
• list_industry_groups(sector, page, page_size, search) — Lists all extant GICS industry groupings
• get_industry_group(group_id) — Retrieves detailed specifications for a GICS industry group identifier
• get_sector(sector_id) — Fetches detailed specifications for a GICS sector identifier
• list_sub_industries(industry, page, page_size, search) — Enumerates all extant GICS sub-industry classifications
• get_sub_industry(sub_industry_id) — Retrieves detailed specifications for a GICS sub-industry identifier
• list_sources(page, page_size) — Enumerates all available data provenance sources
• get_source(source_id) — Fetches detailed metadata for a specified data source
• get_processed_filing(processed_filing_id) — Retrieves the fully processed textual content for a specific filing record
• get_schema(format, lang) — Fetches the OpenAPI 3 specification document for the API interface
• search_companies(params) — Executes searches for corporate entities using identifiers such as name, ISIN, or LEI
• get_company_detail(company_id) — Retrieves comprehensive profile information for a specified corporate entity
• get_latest_filings(params) — Retrieves the most recent set of financial submissions based on criteria
• get_filing_detail(filing_id) — Fetches detailed metadata pertaining to a unique filing record
• list_sectors() — Enumerates all recognized GICS sectors
• list_filing_types() — Enumerates all recognized submission classifications

Supplemental Assets/Utilities

• get_sectors_resource() — Generates a Markdown-formatted catalogue of GICS sectors
• get_filing_types_resource() — Generates a Markdown-formatted catalogue of filing classifications
• get_company_profile(company) — Generates a Markdown-formatted summary profile for an entity
• get_company_recent_filings(company, limit) — Generates a Markdown-formatted manifest of recent corporate submissions

Intent Prompts

• search_company_by_name() — Input elicitation routine for querying entities by their trade name
• find_latest_annual_reports() — Input elicitation routine for locating the most current annual financial submissions

Accessible Data Sources (Resources)

• financial-reports://sectors: Catalogue of all defined GICS sectors
• financial-reports://filing-types: Catalogue of all recognized submission classifications
• financial-reports://companies/{company_id}/profile: Entity profile endpoint
• financial-reports://companies/{company_id}/recent-filings: Endpoint for retrieving recent submissions by entity

Operational Examples

Example 1: Entity Lookup and Data Aggregation

I require analytical material pertaining to Deutsche Bank. Please structure the output to include: 1. Fundamental corporate identifiers: jurisdiction of incorporation, economic sector, and granular industry classification 2. The most recently submitted financial documentation 3. Any available primary financial performance indicators synthesized from these documents

Example 2: Sector-Specific Report Retrieval

I need to examine the newest annual submissions from principal financial institutions operating in Europe. Please execute the following steps: 1. Identify all corporate entities categorized within the banking sector 2. Obtain the most recent annual reporting document for each identified entity 3. If present, synthesize a summary of the core financial figures documented within these retrieved reports

Interoperability Assessment (Platform Support)

The server maintains operational capacity across the following operating systems:

• Linux: Full support across all deployment methods
• macOS: Full support across all deployment methods
• Windows: Full support; however, utilizing the uv package manager is advisable when targeting Claude Desktop

Specific guidance for Windows environments: - For Claude Desktop integration, deployment via uv package is the preferred approach - Docker usage mandates the installation and operation of Docker Desktop for Windows

Debugging and Issue Resolution

Frequently Encountered Problems

1. Communication Failures with Claude Desktop:
2. Verify that the stdio transport protocol is explicitly configured for Claude Desktop integration.

3. For Docker deployments, confirm the inclusion of the interactive flag (-i) during invocation.

4. Dependency Resolution Errors ("Module not found"):

5. Ensure that all prerequisites listed in requirements.txt have been successfully installed via pip install -r requirements.txt.

6. Inability to Establish Connection to MCP Endpoint:

7. Confirm the server process is actively running and that network accessibility (if applicable) or transport channel (stdio) is correctly established between client and server.

8. API Authentication Failures:

9. Scrutinize the credentials supplied within the .env configuration file to validate the API key.

Diagnostic Output (Logging)

When executing the server directly, logs are streamed to the standard console output. For containerized instances, logs can be inspected using the following Docker command:

bash docker logs

Legal Disposition

This software artifact is distributed under the terms of the MIT License, contingent upon appropriate acknowledgment of Data Alchemy Labs. Consult the [LICENSE] file for exhaustive stipulations.