Financial Reports MCP Server by itisaevalex - MCP Server

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)

Install dependencies:

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

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 installation configuration
install.py - Helper for Claude Desktop installation
examples/ - Example scripts and configs
scripts/ - Install scripts

Available Tools

get_filing_type(filing_type_id) — Get detailed information about a filing type by its ID
list_industries(industry_group, page, page_size, search) — List all available GICS industries
get_industry(industry_id) — Get detailed information about a GICS industry
list_industry_groups(sector, page, page_size, search) — List all available GICS industry groups
get_industry_group(group_id) — Get detailed information about a GICS industry group
get_sector(sector_id) — Get detailed information about a GICS sector
list_sub_industries(industry, page, page_size, search) — List all available GICS sub-industries
get_sub_industry(sub_industry_id) — Get detailed information about a GICS sub-industry
list_sources(page, page_size) — List all available data sources
get_source(source_id) — Get detailed information about a data source
get_processed_filing(processed_filing_id) — Get processed content for a filing
get_schema(format, lang) — Get the OpenAPI3 schema for the API
search_companies(params) — Search for companies by name, ISIN, LEI, etc.
get_company_detail(company_id) — Get detailed information about a company
get_latest_filings(params) — Get the latest financial filings
get_filing_detail(filing_id) — Get detailed information about a specific filing
list_sectors() — List all available GICS sectors
list_filing_types() — List all available filing types

Additional Resources/Helpers

get_sectors_resource() — Markdown-formatted list of GICS sectors
get_filing_types_resource() — Markdown-formatted list of filing types
get_company_profile(company) — Markdown-formatted company profile
get_company_recent_filings(company, limit) — Markdown-formatted list of recent filings

Prompts

search_company_by_name() — Prompt for searching a company by name
find_latest_annual_reports() — Prompt for finding latest annual reports

Available Resources

financial-reports://sectors: List of all GICS sectors
financial-reports://filing-types: List of all filing types
financial-reports://companies/{company_id}/profile: Company profile
financial-reports://companies/{company_id}/recent-filings: Recent filings for a company

Examples

Example 1: Search for a company and get its profile

I want to search for information about Deutsche Bank. Please help me find:
1. Basic company details like country, sector and industry
2. Recent financial filings
3. Key financial metrics if available

Example 2: Find the latest annual reports for banks

I'd like to see the latest annual reports from major European banks. 
Please help me:
1. Find companies in the banking sector
2. Get their latest annual reports
3. Summarize key financial metrics from these reports if available

Cross-Platform Compatibility

The server can be run on:

Linux: All methods supported
macOS: All methods supported
Windows: All methods supported, but using uv is recommended for Claude Desktop

For Windows users specifically:

For Claude Desktop, uv-based installation is recommended
Docker requires Docker Desktop for Windows

Troubleshooting

Common Issues

Communication Issues with Claude Desktop:
- Ensure you're using stdio transport when configuring for Claude Desktop
- For Docker, make sure to include the -i flag for interactive mode
"Module not found" errors:
- Make sure all dependencies are installed with pip install -r requirements.txt
Cannot connect to the MCP server:
- Check if the server is running and accessible from the client
Authentication errors with the API:
- Verify your API key in the .env file