annual_report_mcp_server

This MCP server implements three MCP Tools designed to help Claude For Desktop chat with and analyze annual reports and organizational data from Bolagsverket. The tools cover: 1) Fetching and retrieving organizational data from Bolagsverket, 2) Downloading, parsing, and analyzing annual reports, and 3) Identifying organization numbers from company names via the Tavily API. The server also handles automatic token management for Bolagsverket and Tavily API calls, and uses OpenAI via llama-index for embedding and reasoning as part of the analysis workflow. To use these tools, start the MCP server in the environment where you installed it, then invoke the corresponding tool endpoints through Claude or your MCP client. Each tool will prompt for input such as a company name or a specific year, and will return structured results including fetched data, analysis results, and any extracted identifiers.

Typical usage flows include:

• Query a company by name to retrieve its Bolagsverket organizational data and related metadata.
• Provide a financial year or set of URLs to fetch and analyze annual reports, with the server extracting key metrics and generating summaries.
• Use the Tavily integration to map a company name to its organization number, which can then be used to enrich the Bolagsverket data or to perform targeted lookups. The server is designed as a demo/example, so consider it a testing environment for exploring MCP capabilities rather than a production-grade deployment.

Prerequisites:

• Python 3.8+ installed on your system
• Git to clone the repository
• Access to Bolagsverket Valueful Data API (BV API) credentials, and a Tavily API key
• Optional: OpenAI API key for llama-index-based vectorization

Installation steps:

1. Clone the repository and navigate to the project directory: git clone [repository-url] cd annual-report-mcp-server

2. Install Python dependencies: pip install -r requirements.txt

3. Create a configuration file (.env) with required environment variables: OPENAI_API_KEY=your_openai_api_key BV_CLIENT_ID=your_bolagsverket_client_id BV_CLIENT_SECRET=your_bolagsverket_client_secret TAVILY_API_KEY=your_tavily_api_key

4. Run the MCP server locally: python annual_report_mcp_server.py

5. If you plan to integrate with Claude For Desktop, follow the vendor-specific steps to install the MCP server and adjust your claude_desktop_config.json if needed. Note that dependencies or PATH issues may require manual edits to activate virtual environments or adjust the uv runner as shown in the example configuration.

Tips and known considerations:

• This server is intended as a demonstration rather than a production-ready deployment; it may not optimally handle downloaded data at scale.
• Ensure you have valid API access for Bolagsverket and Tavily to avoid authentication errors.
• If you encounter PATH or dependency issues when integrating with Claude For Desktop, you may need to manually activate the virtual environment and adjust the uv command as shown in the example configuration block in the README.
• The integration uses OpenAI via llama-index for embeddings; monitor usage limits and costs associated with OpenAI API usage.
• If you modify endpoints or inputs, ensure you update any client tooling to reflect changes in the MCP Tools interface.