FinanceMCP

[](README_EN.md) # FinanceMCP - Professional Financial Data MCP Server 🚀 [](https://smithery.ai/server/@guangxiangdebizi/finance-mcp) **A professional financial data server based on the MCP protocol, integrating the Tushare API to provide real-time financial data and technical indicator analysis for AI assistants like Claude.** ## 📑 Table of Contents - [🌟 Public Cloud Service (Free)](#-public-cloud-service-free) - [⚡ Core Features](#-core-features) - [🛠️ Tool Overview](#️-tool-overview) - [🎯 Technical Highlights](#-technical-highlights) - [🚀 Quick Start](#-quick-start) - [💡 Example Queries](#-example-queries) - [🔧 Local Deployment](#-local-deployment) - [🆕 Latest Updates](#-latest-updates) - [📄 License](#-license) ## 🌟 Public Cloud Service (Free) **🎉 Ready to use out of the box, no deployment required!** We offer various free public cloud service options: ### 🌐 Web Online Experience Version **🚀 The simplest way to use!** <img width="1920" height="1080" alt="image" src="https://github.com/user-attachments/assets/5a81b053-4d19-4285-b5a2-991d14425595" /> Visit our online experience site: **[http://106.14.205.176:3090/](http://106.14.205.176:3090/)** - ✨ **Zero Configuration Experience** - No setup required, just open the webpage - 🤖 **Integrated Large Model** - Directly converse with AI assistants for financial analysis - 💬 **Intelligent Interaction** - Ask questions in natural language and get real-time financial data - 📱 **Multi-Device Compatibility** - Accessible on computers, phones, and tablets > ⚠️ **Service Note**: This is a personal small server, please use it reasonably and do not attack or abuse it. ### ⚙️ Claude Desktop Configuration #### 🆕 Latest Version (v4.1.0) - Use Your API Key **🎯 Recommended for production environments, configure your own Tushare token:** ```json { "mcpServers": { "finance-mcp": { "disabled": false, "timeout": 600, "type": "streamableHttp", "url": "http://106.14.205.176:8080/mcp", "headers": { "X-Tushare-Token": "Your Tushare Token" } } } } ``` **🔑 How to Obtain Your Tushare Token:** 1. Register an account at [tushare.pro](https://tushare.pro/register) 2. Obtain the API token from your personal center 3. Replace `Your Tushare Token` with your actual token #### 🎁 Traditional Free Service (Limited) You can also use our shared service without an API key (may have rate limits): ```json { "mcpServers": { "finance-data-server": { "disabled": false, "timeout": 600, "type": "sse", "url": "http://106.14.205.176:3101/sse" } } } ``` **Service Advantages:** - ✅ **Latest Version (v4.1.0)** - Use your own API key for unlimited access - ✅ **Available 24/7** - The server runs continuously - ✅ **Full Functionality** - All 14 tools and technical indicators - ✅ **Real-Time Data** - Connects to Tushare professional data - ✅ **No Rate Limits** - Use your own token for unlimited API calls - ✅ **Production Ready** - Stable streamable HTTP protocol > 📺 **Tutorial Video**: [Complete Guide to FinanceMCP](https://www.bilibili.com/video/BV1qeNnzEEQi/) ## ⚡ Core Features ### 🧠 Intelligent Technical Indicator System - **Smart Data Prefetching** - Automatically calculates required historical data, eliminating NaN values - **Mandatory Parameterization** - Requires explicit specification of parameters (e.g., `macd(12,26,9)`) to ensure accuracy - **Modular Architecture** - Parameter parsing, data calculation, and indicator engine are completely decoupled - **5 Core Indicators** - MACD, RSI, KDJ, BOLL, MA ### 🌍 Comprehensive Market Coverage - **10 Major Markets** - A-shares, US stocks, Hong Kong stocks, foreign exchange, futures, funds, bonds, options - **Real-Time News** - Intelligent search of 7+ mainstream financial media - **Macroeconomic Data** - 11 economic indicators (GDP, CPI, PPI, PMI, etc.) - **Company Analysis** - Financial statements, management information, shareholder structure ## 🛠️ Tool Overview | Tool Name | Function Description | Core Features | |-----------|---------------------|----------------| | 🕐 **current_timestamp** | Current timestamp | UTC+8 timezone, multiple output formats | | 📰 **finance_news** | Financial news search | Baidu news crawler; input: `query` (multiple keywords separated by spaces, OR filter) | | 📈 **stock_data** | Stock/Crypto + Technical Indicators | 10 major markets + crypto (Binance by default) + 5 technical indicators, smart prefetching | | 📊 **index_data** | Index data | Historical data of major market indices | | 🧱 **csi_index_constituents** | CSI index constituents and weight summary | Supports only CSI (China Securities Index Company), index interval market + constituent stock weight and interval rise and fall + valuation/financial indicators (PE, PB, dividend yield, ROE, ROA, net profit margin, operating cash flow, debt ratio, revenue year-on-year, asset turnover, gross margin, three expense ratios, cash dividend rate) | | 📉 **macro_econ** | Macroeconomic data | 11 indicators: GDP/CPI/PPI/PMI/Shibor, etc. | | 🏢 **company_performance** | A-share company financial analysis | Financial statements + management + fundamentals, 13 data types | | 🏛️ **company_performance_hk** | Hong Kong stock company financial analysis | Hong Kong stock profit statement, balance sheet, cash flow statement | | 🇺🇸 **company_performance_us** | US stock company financial analysis | 4 major financial statements of US stocks + comprehensive financial indicator analysis | | 💰 **fund_data** | Fund data | Net value/holdings/dividends, 85% performance optimization | | 👨‍💼 **fund_manager_by_name** | Fund manager query | Personal background, list of managed funds | | 🪙 **convertible_bond** | Convertible bond data | Basic information + issuance data + conversion terms | | 🔄 **block_trade** | Block trade data | Trade details + counterparty information | | 💹 **money_flow** | Capital flow data | Analysis of main force/super large orders/large orders/medium orders/small orders | | 💰 **margin_trade** | Margin trading data | 4 APIs: underlying stock/summary/details/transfer margin | | 🐯 **dragon_tiger_inst** | Dragon Tiger List institutional details | Specify trading day (optional code), buy/sell amount/proportion/net amount/reason table | | 🔥 **hot_news_7x24** | 7×24 Hot Topics | Based on the latest batch from Tushare (up to 1500 entries at a time), content similarity 80% deduplication, entries separated by `---` | ## 🎯 Technical Highlights ### Intelligent Technical Indicator Engine ``` User Request → Parameter Parsing → Data Requirement Calculation → Extended Historical Data Retrieval → Indicator Calculation → Result Return ``` **Supported Indicators:** - **MACD** `macd(12,26,9)` - Trend analysis - **RSI** `rsi(14)` - Overbought and oversold judgment - **KDJ** `kdj(9,3,3)` - Stochastic indicator - **BOLL** `boll(20,2)` - Bollinger Bands - **MA** `ma(5/10/20/60)` - Moving average ### Core Technical Advantages 1. **Smart Prefetching** - Automatically calculates and retrieves additional historical data required for indicators 2. **Mandatory Parameters** - Avoids calculation discrepancies caused by default parameters 3. **High Performance** - Fund data query performance improved by 85% (5.2s → 0.8s) 4. **Data Integration** - Seamless integration of 43+ Tushare API interfaces ## 🚀 Quick Start ### 1. Use Public Cloud Service (Recommended) Copy the JSON configuration above into the Claude desktop configuration file, and restart Claude to start using it! ### 2. Configuration File Location - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` ### 3. Start Using Once configured, simply ask questions in Claude! ## 💡 Example Queries <details> <summary><strong>📈 Stock Technical Analysis</strong></summary> ``` "Analyze the technical condition of Moutai (600519.SH), calculate MACD(12,26,9), RSI(14), KDJ(9,3,3)" "Check the Bollinger Bands BOLL(20,2) and four moving averages MA(5,10,20,60) for CATL (300750.SZ)" "Analyze the stock price trend and MACD indicator for Apple Inc. (AAPL) over the past month" ``` </details> <details> <summary><strong>📊 Comprehensive Analysis</strong></summary> ``` "Comprehensive analysis of BYD: financial status, technical indicators, capital flow, latest news" "Compare the performance of A-shares, US stocks, and Hong Kong stocks, including major indices and technical indicators" "Assess the investment value of CATL: fundamentals + technicals + capital flow" "Get the CSI constituent stock summary for CSI 300 (000300.SH) from 2024-01-01 to 2024-06-30" ``` </details> <details> <summary><strong>🧱 CSI Index Constituents and Weights (Including Valuation/Financials)</strong></summary> ``` "Get the constituent stock summary for China Securities Company (399975.SZ) from 2024-01-01 to 2024-06-30 (including PE, PB, dividend yield, ROE, ROA, net profit margin, operating cash flow, debt ratio, revenue year-on-year, asset turnover, gross margin, three expense ratios, cash dividend rate)" ``` </details> <details> <summary><strong>📰 News and Macroeconomics</strong></summary> ``` "Search for the latest policies and market dynamics in the new energy vehicle sector" "Analyze the current macroeconomic situation: GDP, CPI, PPI, PMI data" "The impact of the Federal Reserve's interest rate hike on the Chinese stock market, related news and data" ``` </details> <details> <summary><strong>💰 Funds and Bonds</strong></summary> ``` "Query the latest net value and holding structure of CSI 300 ETF" "Analyze Zhang Kun's fund performance" "Overview of the convertible bond market and investment opportunities" ``` </details> <details> <summary><strong>🏛️ Hong Kong Stock Analysis</strong></summary> ``` "Get the profit statement for Tencent Holdings (00700.HK) for 2024, including key financial ratios" "Analyze Alibaba (09988.HK) balance sheet and financial structure" "Compare the cash flow performance of China Construction Bank (00939.HK) over multiple periods" ``` </details> <details> <summary><strong>🐯 Dragon Tiger List</strong></summary> ``` "Query the institutional details of the Dragon Tiger List for 20240525" "Query the institutional details of the Dragon Tiger List for 20240525 (focusing on 000001.SZ)" ``` </details> <details> <summary><strong>🇺🇸 US Stock Analysis</strong></summary> ``` "Analyze Nvidia (NVDA) financial performance for 2024, including profit statement and cash flow" "Get the balance sheet for Apple (AAPL), focusing on cash reserves and debt structure" "Compare Tesla (TSLA) financial indicators over multiple periods, analyzing trends in profitability" "View Microsoft's (MSFT) comprehensive financial indicators, including ROE, ROA, gross margin, etc." ``` </details> <details> <summary><strong>🪙 Crypto Assets</strong></summary> ``` "View the trend of Bitcoin (BTC-USD) from 2024-01-01 to 2024-06-30, calculate MACD(12,26,9) and RSI(14)" "View the daily trend of USDT against CNY: market_type=crypto, code=USDT.CNY, start_date=20240101, end_date=20240630" "Use CoinGecko id for query: market_type=crypto, code=bitcoin.usd, indicators=\"boll(20,2) ma(5) ma(10)\"" ``` </details> ## 🔧 Local Deployment (Streamable HTTP) <details> <summary><strong>🛠️ Complete Local Deployment Guide</strong></summary> If you need to deploy locally, please follow these steps: ### Environment Requirements - **Node.js >= 18** - Download from [nodejs.org](https://nodejs.org/) - **Tushare API Token** - Obtain from [tushare.pro](https://tushare.pro) <details> <summary><strong>📝 How to Obtain Tushare API Token</strong></summary> 1. **Register an Account** - Visit [tushare.pro](https://tushare.pro/register) to register 2. **Obtain Token** - Get the API token from your personal center 3. **Point Explanation** - Some premium data requires points **Student Benefits** - Apply for 2000 free points: - Follow Tushare's official Xiaohongshu and interact - Join the student QQ group: **290541801** - Complete personal information (school email/student ID) - Submit application materials to the administrator </details> ### Installation Steps #### Method 1: Install via npm package (Recommended) ```bash # Global installation npm install -g finance-mcp # Or local installation npm install finance-mcp ``` After installation, you can use it directly: ```bash # If installed globally finance-mcp # If installed locally npx finance-mcp ``` #### Method 2: Install via Smithery ```bash npx -y @smithery/cli install @guangxiangdebizi/finance-mcp --client claude ``` #### Method 3: Manual Installation ```bash # 1. Clone the repository git clone https://github.com/guangxiangdebizi/FinanceMCP.git cd FinanceMCP # 2. Install dependencies npm install # 3. Configure API key echo "TUSHARE_TOKEN=your_token_here" > .env # Or directly edit src/config.ts # 4. Build the project npm run build ``` ### Start the Service **Streamable HTTP Mode (Recommended)** ```bash npm run build node build/httpServer.js # Or npm run start:http ``` **SSE Mode** ```bash npm run build npm run start:sse ``` After the service starts: - MCP Endpoint: `http://localhost:3000/mcp` - Health Check: `http://localhost:3000/health` ### Claude Configuration Configuration file location: - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` #### Latest Configuration: Streamable HTTP Mode (Pass Token via Header) ```json { "mcpServers": { "finance-data-server": { "type": "streamableHttp", "url": "http://localhost:3000/mcp", "timeout": 600, "headers": { "X-Tushare-Token": "your_tushare_token" } } } } ``` #### Header Rules for Passing Token - Priority reads from `X-Tushare-Token`; - If not provided, it tries `Authorization: Bearer <token>`; - Falls back to read `X-Api-Key`; - If not provided in the header, it falls back to use the server environment variable `TUSHARE_TOKEN` (optional). (The crypto market defaults to using Binance's public market interface, no cryptocurrency API Key required) ### Verify Installation After configuration, restart the Claude desktop version and ask: "Get the current time." If it returns time information, the installation is successful. </details> ## 🆕 Latest Updates ### 🚀 Version 4.1.0 - Cryptocurrency Support Version **Latest Major Update**: We have released version v4.1.0, adding support for cryptocurrency market data and enhanced features! <details> <summary><strong>🎯 New Features in v4.1.0</strong></summary> - **₿ Cryptocurrency Market Data** - Real-time cryptocurrency prices, trading volumes, and market analysis - **🔗 Multi-Exchange Support** - Data from major cryptocurrency exchanges - **📊 Cryptocurrency Technical Indicators** - Providing MACD, RSI, KDJ, BOLL, MA indicators for digital assets - **💹 Market Cap and Volume Analysis** - Comprehensive cryptocurrency market indicators - **🌐 Web Online Experience** - New web interface `http://106.14.205.176:3090/` - **🤖 Integrated Large Model** - Directly converse with AI assistants for financial analysis - **💬 Intelligent Interaction** - Ask questions in natural language and get real-time financial data - **📱 Multi-Device Compatibility** - Accessible on computers, phones, and tablets - **✨ Zero Configuration Experience** - No setup required, just open the webpage - **📦 NPM Package** - Now published in the npm registry under the name `finance-mcp` - **🌐 Public Cloud Service** - Production-ready deployment address `http://106.14.205.176:8080/mcp` - **🔑 Custom API Key** - Use your own Tushare token for unlimited access - **⚡ Streamable HTTP** - Enhanced protocol support for better performance - **🛡️ Production Stability** - Improved error handling and session management - **📈 No Rate Limits** - Use your own token for unlimited API calls - **🔧 Easy Installation** - Simple npm installation and configuration **Migration Guide**: Update your Claude configuration to use the new streamable HTTP endpoint and your own API key for the best experience. </details> ### 🧱 Enhanced CSI Index Constituents Summary Tool (NEW!) - Index interval market + constituent stock weight and interval rise and fall - Added valuation/financial indicators: PE (TTM), PB, dividend yield, ROE, ROA, net profit margin, operating cash flow per share, debt ratio, revenue year-on-year, asset turnover, gross margin, three expense ratios, cash dividend rate - Supports CSI index codes in `.SH/.SZ` format (e.g., `399975.SZ`), automatically falling back to find the most recent weight date and valuation date ### 🇺🇸 US Stock Financial Analysis Module (NEW!) **Recently Added**: We have added complete US stock financial analysis functionality! <details> <summary><strong>📊 New Features</strong></summary> - **🇺🇸 company_performance_us** - Professional US stock financial analysis tool - **📈 Profit Statement Analysis** - Revenue, gross margin, net profit, earnings per share analysis - **💰 Balance Sheet Analysis** - Asset, liability, equity structure, and financial ratios - **💸 Cash Flow Statement Analysis** - Operating, investing, financing cash flows, and free cash flow - **📊 Comprehensive Financial Indicators** - ROE, ROA, profitability, growth, solvency, etc. - **🎯 Intelligent Data Processing** - Multi-period comparative analysis, trend calculation, key indicator extraction - **🌟 Bilingual Compatibility** - Supports intelligent recognition of financial terms in both Chinese and English **Supported Companies**: Covers major US stocks and Chinese concept stocks, including Nvidia (NVDA), Apple (AAPL), Tesla (TSLA), Microsoft (MSFT), etc. **API Integration**: Based on [Tushare US stock financial data API](https://tushare.pro/document/2?doc_id=394), complete integration of 4 major data interfaces. </details> ### 🏛️ Hong Kong Stock Financial Analysis Module **Added**: We have added comprehensive Hong Kong stock financial analysis functionality! <details> <summary><strong>📊 Feature Highlights</strong></summary> - **🏛️ company_performance_hk** - Dedicated Hong Kong stock financial analysis tool - **📈 Profit Statement Analysis** - Revenue, profit margin, earnings per share, comprehensive income analysis - **💰 Balance Sheet Analysis** - Asset, liability, equity structure, and key financial ratios - **💸 Cash Flow Statement Analysis** - Operating, investing, financing activities, and free cash flow calculation - **🎯 Intelligent Data Processing** - Automatic financial ratio calculation and multi-period comparative analysis - **🌟 Enhanced User Experience** - Structured tables, intelligent classification, trend analysis **Supported Companies**: All companies listed on the Hong Kong Stock Exchange, including Tencent (00700.HK), Alibaba (09988.HK), China Construction Bank (00939.HK), etc. **API Integration**: Based on [Tushare Hong Kong stock financial data API](https://tushare.pro/document/2?doc_id=389), complete data format optimization. </details> ## 📄 License This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. --- **👨‍💻 Author**: Chen Xingyu **📧 Email**: guangxiangdebizi@gmail.com **🔗 GitHub**: [guangxiangdebizi](https://github.com/guangxiangdebizi) ⭐ If this project helps you, please give us a Star!