Corporate Financial Intelligence Gateway

🎬 Demonstration

This MCP (Model Context Protocol) gateway serves as a conduit to the underlying Financial Reports external service, furnishing the necessary utilities and datasets for retrieving corporate regulatory filings, standardized industry classifications, and associated operational metrics.

Core Capabilities

• Execute lookups for entities based on nomenclature, domicile, or economic classification.
• Fetch comprehensive organizational specifics.
• Acquire the most recent regulatory disclosures and statements.
• Query established industry classification taxonomies.
• Retrieve granular details and complete textual content of submitted documentation.

Prerequisites for Operation

• Runtime Environment: Python version 3.11 or newer is mandatory.
• Containerization: Docker deployment is highly suggested for consistency.
• Local Orchestration: FastMCP framework utilization (if deploying on a non-server environment).
• Configuration Handling: Integration of the dotenv package for local credential management.

Notice: The current implementation relies exclusively on the live, production Financial Reports API. All legacy mock service code paths and configuration mocks have been deprecated to enhance operational stability and data accuracy.

🚀 Deployment Guide

Deployment can be achieved through several distinct methods. Select the approach most suitable for your deployment environment:

Method 1: Containerization via Docker (Preferred)

Docker is endorsed for achieving reproducible environments, process isolation, and simplified setup procedures.

bash

Initial image construction (execute once)

docker build -t financial-reports-mcp .

Service invocation

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 leveraging Docker Compose:

bash

Configuration file setup

echo "Clone .env.example into .env and populate secrets" cp .env.example .env

Initiate associated services

docker-compose up

For integration within the Claude Desktop application, utilize the following manifest configuration. For optimal security and portability across client execution contexts, inject sensitive credentials via -e flags within the args field:

{ "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: Explicitly supplying secrets via command-line arguments (-e) within the args array ensures the Docker daemon receives these parameters unambiguously, irrespective of the host client's method for propagating environment variables. This yields the most resilient and universally compatible deployment strategy for environments like Claude Desktop.

Method 2: Utilizing the Smithery CLI (For Claude Integration)

Employ the Smithery command-line utility to manage installation and execution within the Claude framework:

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

Method 3: Direct Python Execution (Development/Validation)

1. Dependency resolution: bash python -m venv venv # Environment isolation venv\Scripts\activate # Activation on Windows systems pip install -r requirements.txt

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

Alternatively, using the uv package manager

uv run src/financial_reports_mcp.py

Insight: When utilizing uv, the environment automatically sources the configuration variables defined in the .env file located at the project root.

Operational Artifacts

All illustrative code samples and configuration manifests are archived within the examples/ subdirectory. Examples include:

• examples/test_server.py — Script to execute the comprehensive MCP validation 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 — Illustrative demonstration of Python client interaction.

Execute the validation suite via: bash python examples/test_server.py

Configuration Variables

Establish a file named .env in the top-level directory and populate it with the following environment parameters:

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

System Architecture Map

• src/ — Primary source code repository
• financial_reports_mcp.py — The primary execution module for the MCP service (where all defined functionalities reside).
• api_client.py — Factory module responsible for initializing API communication instances.
• real_api/real_client.py — Concrete implementation of the live API interaction logic.
• .env - Runtime environment variables (excluded from version control).
• requirements.txt - Declaration of project dependencies.
• Dockerfile & docker-compose.yml - Definitions for containerized deployment.
• setup.py - Metadata for package distribution.
• install.py - Utility script assisting with Claude Desktop integration.
• examples/ - Directory housing reference scripts and configuration examples.
• scripts/ - Scripts related to installation procedures.

Accessible Toolkit Functions

• get_filing_type(filing_type_id) — Retrieves exhaustive metadata for a filing classification identified by its unique code.
• list_industries(industry_group, page, page_size, search) — Enumerates all available GICS industry classifications, supporting pagination and filtering.
• get_industry(industry_id) — Fetches granular data pertaining to a specific GICS industry classification.
• list_industry_groups(sector, page, page_size, search) — Lists all defined GICS industry groupings, supporting filtering.
• get_industry_group(group_id) — Obtains detailed specifications for a designated GICS industry group identifier.
• get_sector(sector_id) — Retrieves comprehensive details associated with a GICS sector identifier.
• list_sub_industries(industry, page, page_size, search) — Provides a paginated listing of GICS sub-industries, filterable by parent industry.
• get_sub_industry(sub_industry_id) — Fetches the complete profile for a GICS sub-industry identifier.
• list_sources(page, page_size) — Returns a paginated directory of all integrated data reporting channels.
• get_source(source_id) — Retrieves specific information about a defined data reporting source.
• get_processed_filing(processed_filing_id) — Accesses the rendered, analyzed content for a specified processed disclosure document.
• get_schema(format, lang) — Publishes the current OpenAPI3 specification document for the API endpoint, optionally localized.
• search_companies(params) — Executes targeted queries against company registries using identifiers like name, ISIN, or LEI.
• get_company_detail(company_id) — Fetches the full descriptive record for an organization identified by its unique identifier.
• get_latest_filings(params) — Queries for the most recent set of submitted corporate financial disclosures, subject to parameters.
• get_filing_detail(filing_id) — Retrieves metadata and context for an individual disclosure document.
• list_sectors() — Outputs a complete enumeration of all defined GICS sectors.
• list_filing_types() — Generates a list detailing all recognized regulatory disclosure categories.

Supplementary Data Providers/Utilities

• get_sectors_resource() — Generates a Markdown-formatted inventory of GICS sectors.
• get_filing_types_resource() — Generates a Markdown-formatted catalog of recognized filing formats.
• get_company_profile(company) — Renders a Markdown summary of an organization's profile.
• get_company_recent_filings(company, limit) — Produces a Markdown list summarizing the most recent submissions for a specified entity.

Conversational Interface Prompts

• search_company_by_name() — Interactive subroutine to solicit and execute a company name search.
• find_latest_annual_reports() — Interactive subroutine designed to locate the most recent statutory annual reports.

Accessible Data Endpoints (Resources)

• financial-reports://sectors: Complete inventory of GICS sectors.
• financial-reports://filing-types: Comprehensive registry of available disclosure formats.
• financial-reports://companies/{company_id}/profile: Dedicated endpoint for organizational blueprint retrieval.
• financial-reports://companies/{company_id}/recent-filings: Endpoint providing access to the chronological list of recent submissions.

Use Case Illustrations

Scenario 1: Entity Identification and Data Retrieval

I require intelligence on Deutsche Bank. Specifically, I need the following outputs: 1. Core corporate attributes: jurisdiction, assigned sector, and specific industry code. 2. The most current financial disclosure documents. 3. Any aggregated key performance indicators that are readily accessible.

Scenario 2: Comparative Analysis of European Financial Institutions

My objective is to review the latest statutory annual reports for prominent European banking entities. Please execute the following sequence: 1. Isolate all constituent companies categorized under the 'Banking' GICS sector. 2. Secure their newest officially filed annual reports. 3. If financial aggregates are present within those filings, synthesize a summary of key metrics.

Interoperability Matrix

The service runtime is validated across major operating systems:

• Linux: Full compatibility across all execution methods.
• macOS: Full compatibility across all execution methods.
• Windows: All methods are supported, though the uv installation path is favored when interfacing with Claude Desktop.

Specific guidance for Windows users: - When using Claude Desktop, deployment via uv integration is the recommended procedure. - Docker utilization mandates the presence and configuration of Docker Desktop for Windows.

Common Operational Hurdles

Interaction Failures with Claude Desktop

1. Verification: Confirm that the stdio transport mechanism is selected during the Claude Desktop configuration phase.

2. Docker Context: Ensure the interactive flag (-i) is explicitly included in Docker invocation parameters.

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

4. Validate that all prerequisite libraries have been successfully resolved via pip install -r requirements.txt.

5. Inability to Establish Service Connection:

6. Confirm the server process is actively running and network accessibility has not been obstructed.

7. API Credential Rejection (Authentication failures):

8. Double-check the validity and placement of the API key within the designated .env configuration file.

Monitoring Logs

When running the server as a standalone process, output streams directly to the terminal. For containerized deployments, log inspection is performed using:

bash docker logs

Licensing Declaration

This software component is distributed under the terms of the MIT License, contingent upon appropriate acknowledgement of Data Alchemy Labs as the original creator. Refer to the dedicated [LICENSE] document for comprehensive stipulations.

WIKIPEDIA: Business management tools encompass the entire spectrum of systems, applications, control mechanisms, analytical solutions, and governing methodologies employed by corporate entities to effectively navigate market volatility, secure a sustained competitive stance, and drive enhanced operational efficacy.

== Conceptual Framework == Management apparatuses are departmentalized, aligning with specific organizational functions. Categorizations might include tools for strategic planning, workflow management, record keeping, human capital oversight, decision support, and performance auditing. A functional taxonomy typically encompasses:

Instrumentation for data ingestion and integrity validation across all functional units. Systems designed for monitoring and optimizing enterprise processes. Platforms facilitating data aggregation and executive decision enablement. Contemporary business tooling has undergone rapid transformation over the preceding decade, propelled by swift technological advancement, creating complexity in selecting optimal solutions for diverse organizational profiles. This situation is fueled by continuous pressure to minimize expenditure, maximize revenue realization, deeply comprehend client requirements, and efficiently deliver requisite products in the manner demanded by the market. Within this dynamic environment, leadership must adopt a strategic posture regarding management technology adoption, rather than simply integrating the newest available solution. Over-reliance on unmodified, off-the-shelf tools often leads to systemic instability. Therefore, business management instrumentation must be judiciously chosen and subsequently tailored to fit the specific demands of the enterprise, not the inverse.

== Predominant Selections == A 2013 study conducted by Bain & Company quantified the global utilization patterns of various business management instruments. The results reflect regional priorities shaped by economic downturns and shifting corporate landscapes. The top ten instrumentalities identified included:

Strategic formulation methodologies Customer lifecycle management systems Employee morale assessment programs Competitive analysis frameworks Integrated performance measurement (Balanced Scorecard) Identification of core organizational strengths Offshoring/Outsourcing strategy implementation Organizational adaptation initiatives Logistics and material flow optimization Formalized organizational purpose and vision statements Market segmentation analysis Total Quality Management protocols

== Corporate Software Applications == Software, defined as a set of computational programs utilized by business personnel to execute various operational tasks, is commonly termed business software or an enterprise application. These solutions are employed to elevate output levels, rigorously quantify performance metrics, and execute diverse corporate functions with high fidelity. The progression started with rudimentary Management Information Systems (MIS) and expanded into comprehensive Enterprise Resource Planning (ERP) suites. Subsequently, Customer Relationship Management (CRM) capabilities were integrated, culminating in the current paradigm of cloud-based business management suites. While a demonstrable linkage exists between IT investment intensity and organizational success, two factors are paramount for delivering tangible value: the efficacy of the deployment process and the precision in selecting and adapting the appropriate technological instruments.