Yazhodha/stock-mcp-server

Stock Investment MCP Server

A comprehensive Model Context Protocol (MCP) server that provides Claude Desktop with seamless access to Sri Lankan stock market data, enabling professional-grade investment analysis and portfolio management through natural language conversations.

🎯 Project Overview

This MCP server serves as the authoritative data provider for Colombo Stock Exchange (CSE) market data, enabling users to:

• Analyze stock performance and fundamentals
• Manage investment portfolios
• Get real-time market insights
• Compare stocks and sectors
• Track portfolio performance

🏗️ Architecture

Built using Clean Architecture principles with .NET 8:

StockMCP.sln
├── StockMCP.Domain/          # Core business logic and entities
├── StockMCP.Application/     # Application services and interfaces
├── StockMCP.Infrastructure/  # External integrations (CSE APIs, Database)
└── StockMCP.API/            # MCP tools and server implementation

📊 Core Features

MCP Tools (15 Total Planned)

• Stock Data Tools (4): Current prices, fundamentals, company info, historical data
• Market Analysis Tools (5): Market overview, sector performance, stock search/comparison
• Portfolio Management Tools (6): Create/manage portfolios, track performance

Data Sources

• Primary: CSE (Colombo Stock Exchange) official APIs
• Backup: Yahoo Finance for validation
• Financial Reports: User-uploaded PDFs analyzed by Claude (hybrid approach)

🔧 Technology Stack

• .NET 8 - Core framework
• ModelContextProtocol v0.3.0-preview.4 - MCP SDK for Claude Desktop integration
• Entity Framework Core 9.0.9 - Data access with SQLite/SQL Server support
• Clean Architecture - Modular, maintainable design
• Microsoft.Extensions.Http - HTTP client management
• Newtonsoft.Json - JSON serialization

📋 Current Status: Phase 1 Complete ✅

✅ Completed

• Clean Architecture solution structure
• .NET 8 projects with MCP SDK integration
• Domain entities with CSE sector classifications
• Entity Framework DbContext with optimized configurations
• Value objects and enums for type safety
• Comprehensive database schema design

Domain Models

• Stock - Company information with CSE-specific fields
• StockPrice - Real-time and historical price data
• Portfolio - Investment portfolio management
• PortfolioHolding - Individual stock positions
• FundamentalData - Market-derived and calculated metrics
• MarketData - Market indices and overview data

🚀 Next Phase: Application Services & API Integration

• Application layer services and interfaces
• CSE API client implementation
• First 3 MCP tools (get_stock_data, get_market_overview, get_company_info)
• MCP server configuration and Claude Desktop integration

🔄 Data Strategy

Hybrid Approach for Maximum Flexibility

• MCP Server: Provides real-time market data, portfolio management, technical analysis
• Claude PDF Analysis: Handles complex financial report analysis (annual reports, balance sheets)
• Combined Power: Users get both real-time data and comprehensive financial insights

Caching Strategy

• Stock prices: 30 seconds (real-time during market hours)
• Company data: 1 hour
• Market summary: 2 minutes
• Portfolio data: 5 minutes

📈 CSE Integration

Supported Sectors (25 Official Classifications)

Application Software, Banking, Finance, Insurance, Beverage/Food/Tobacco, Chemicals/Pharmaceuticals, Commercial/Professional Services, Construction/Engineering, Diversified, Footwear/Textile, Health Care, Hotels, Information Technology, Investment Trusts, Land/Property, Manufacturing, Motor, Oil Palms, Plantations, Power/Energy, Services, Stores/Supplies, Telecommunications, Trading, Transportation, Other

API Endpoints

• Primary: https://www.cse.lk/api/list_by_market_cap
• Additional endpoints to be integrated for comprehensive market coverage

🛠️ Development Approach

Reference Projects

• Weather-MCP: MCP SDK implementation patterns
• CSEInvestmentTool: Proven CSE API integration and data models

Quality Standards

• Clean Architecture principles
• Comprehensive error handling
• Industry best practices
• Extensive documentation
• Performance optimization

📝 Documentation

• - Architectural decisions and rationale
• - Complete project specifications and requirements

🚦 Getting Started

Prerequisites

• .NET 8 SDK
• Visual Studio 2022 or VS Code
• Claude Desktop (for MCP integration)

Build and Run

# Clone the repository
git clone [repository-url]

# Build the solution
dotnet build StockMCP.sln

# Run the MCP server (after implementation complete)
dotnet run --project StockMCP.API

Database Setup

The project supports both SQLite (development) and SQL Server (production). Entity Framework migrations will be added in the next phase.

🤝 Contributing

This project follows Clean Architecture principles and maintains comprehensive documentation of all decisions. See for detailed architectural rationale.

📄 License

[License information to be added]

Status: Phase 1 Foundation Complete ✅ | Build Status: ✅ 0 Errors, 0 Warnings