japan-stock-mcp

# Japan Stock MCP Server Claude Desktop provides a financial analysis and stock screening MCP server for Japan stocks. **Data Sources** - Annual financial data: [EDINET](https://disclosure.edinet-fsa.go.jp/) (Financial Services Agency, XBRL) - Quarterly financial data: [J-Quants API](https://jpx-jquants.com/) (JPX official, all listed companies) - Stock prices and valuations: [yfinance](https://github.com/ranaroussi/yfinance) (Yahoo Finance) **Target Stocks**: Approximately 3,800 companies listed on the Tokyo Stock Exchange. ## Architecture ### Production Configuration (AWS Serverless) ``` Claude Desktop ↓ MCP Streamable HTTP (x-api-key authentication) [API Gateway HTTP API + Custom Domain] ↓ [Lambda: stock-mcp-server] Python 3.12, zip, SnapStart, 60s ↓ [Aurora Serverless v2 PostgreSQL 16.6] us-east-1 ↑ [Lambda: stock-mcp-batch] Container, 15min, 512MB ↑ ↑ [SF: stock-mcp-weekly-sync] [SF: stock-mcp-tridaily-sync] EDINET incremental data only Stock prices → Quarterly data (chunk parallel) ↑ ↑ [EventBridge] Every Sunday 20:00 JST [EventBridge] Every Wednesday and Saturday 20:00 JST ``` **Monthly Cost Estimate**: ~$2〜5 (Aurora ~$1〜3 + Secrets Manager ~$1.20) For details, refer to [docs/aws/aws-architecture.md](docs/aws/aws-architecture.md) (role and cost basis of each resource, beginner's guide). For AWS environment maintenance procedures (adding tools, batch corrections, schema changes, etc.), refer to [docs/aws/aws-maintenance.md](docs/aws/aws-maintenance.md). For AWS initial deployment procedures, refer to [docs/aws/aws-initial-setup.md](docs/aws/aws-initial-setup.md). ### Local Development Mode (SQLite) ``` Claude Desktop (Windows) │ wsl.exe bash -lc ▼ MCP Server (WSL / Python / uv) ← app/ │ SQLite ▼ stocks.db (data/) ▲ Batch (Docker) ← batch/ ├── EDINET API → XBRL parsing → financials table (annual) ├── J-Quants API → financials table (quarterly) └── yfinance → prices table (stock prices) ``` ## Setup ### Prerequisites (Common) - WSL2 (Ubuntu) - [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`) - Docker Desktop for Windows (with WSL2 integration) - Claude Desktop - EDINET API key (application page: [https://disclosure2.edinet-fsa.go.jp/](https://disclosure2.edinet-fsa.go.jp/)) - J-Quants account and Light plan (¥1,650/month) API key (J-Quants: [https://jpx-jquants.com/](https://jpx-jquants.com/)) ## Tool List | Tool | Description | |--------|------| | `screen_stocks` | Filter stocks by ROE, PER, PBR, operating profit margin, quarterly YoY growth rate, etc. | | `get_financials` | Retrieve a company's financial data annually (default 5 years) | | `get_quarterly_financials` | Retrieve a company's quarterly financial data (QoQ and YoY growth rates) | | `compare_companies` | Compare financial metrics of multiple companies side by side | | `compare_to_sector` | Evaluate a company's metrics within its sector percentile | | `get_valuation_metrics` | Retrieve a company's stock price and valuation metrics (PER, PBR, market capitalization, etc.) | | `get_company_info` | Retrieve a company's basic information and latest financial summary | | `list_sectors` | List sectors and the number of stocks | | `get_annual_report_section` | Retrieve a section of an annual securities report in text format | | `get_annual_report_pages` | Retrieve specified pages of an annual securities report in PDF (base64) format | | `update_data` | Update annual financial data from EDINET | | `update_prices` | Update stock prices and valuations using yfinance | | `update_quarterly` | Update quarterly financial data using J-Quants API | | `check_batch_status` | Check the progress of batch processing | | `backup_db` | Backup the database locally (SQLite mode only) | | `list_backups` | List backups (SQLite mode only) | | `restore_db` | Restore the database from a backup (SQLite mode only) | ## Usage Examples ### Stock Screening ``` Show me stocks in the electronics sector with ROE > 15% and PER < 20. → screen_stocks(sector="electronics", roe_min=15, per_max=20) ``` ### Financial Trend Analysis ``` Show me Nintendo's financial performance over the past 5 years. → get_financials(code="7974", years=5) ``` ### Peer Company Comparison ``` Compare Sony, Panasonic, and Hitachi. → compare_companies(codes=["6758", "6752", "6501"]) ``` ### Quarterly Growth Rate Stock Screening ``` Find stocks in the electronics sector with quarterly revenue growth > 10% YoY. → screen_stocks(sector="electronics", quarterly_revenue_growth_min=10) ``` ### Annual Report Section Retrieval ``` Retrieve Nintendo's business overview from its annual report. → get_annual_report_section(sec_code="7974", section="Business Overview") ```