stock-mcp-server

Yazhodha/stock-mcp-server

3.2

If you are the rightful owner of stock-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Stock Investment MCP Server provides seamless access to Sri Lankan stock market data for professional-grade investment analysis and portfolio management.

Tools
3
Resources
0
Prompts
0

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