FinanceMCP Financial Data Server

Welcome to FinanceMCP Financial Data Server! This project provides a Model Context Protocol (MCP) server that enables language models (such as Cline) to access real-time financial news, stock data, index data, and macroeconomic data through the Tushare API. This makes it possible to conduct insightful analysis and predictions based on the latest market information.

This guide will walk you through setting up, configuring, and using this server, even if you are new to MCP or Node.js development.

🌟 Features

• Comprehensive Financial Data Access: Obtain stock, index, financial news, and macroeconomic data via the Tushare API.
• Stock Data Access: Retrieve historical market data for specified stock codes.
• Index Data Access: Fetch historical market data for major indices such as the Shanghai Composite Index and Shenzhen Component Index.
• Financial News Retrieval: Collect the latest financial news from various sources (via the Tushare API).
• Macroeconomic Data: Access macroeconomic indicators such as Shibor rates, LPR rates, GDP, CPI, PPI, etc.
• MCP Integration: Seamless integration with MCP-compatible clients (e.g., Cline).
• Configurable: Easily set up and customize through a simple JSON configuration file.
• Extensible: Designed to be easily extended with new Tushare API interfaces or custom tools.

🚦 System Requirements

Before you begin, ensure that the following software is installed on your system:

1. Node.js and npm:

   • This project is built on Node.js. We recommend using the latest LTS (Long-Term Support) version.

   • You can download it from nodejs.org.

   • npm (Node Package Manager) comes pre-installed with Node.js.

   • To check if they are installed, open a terminal or command prompt and enter:
     bash
     node -v
     npm -v

     You should see the corresponding version numbers.

2. Git (Optional but Recommended):

   • If you want to clone the repository directly from Git.
   • You can download it from git-scm.com.

3. MCP Client (e.g., Cline):

   • To interact with this server, you need an MCP client. This guide will use Cline as an example.

4. Tushare API Token:

   • This project relies on financial data provided by Tushare. You need to register on the Tushare website and obtain an API Token.
   • Please visit https://tushare.pro/register to register.
   • The obtained Token will be used directly in the code.

🛠️ Installation and Setup

Follow these steps to get your server up and running:

Installing FinanceMCP

Installing via Smithery

To automatically install FinanceMCP for Claude Desktop via Smithery:

bash
npx -y @smithery/cli install @guangxiangdebizi/FinanceMCP --client claude

1. Get the Code

• If you have Git installed: Clone the repository to your local machine:
  bash
  git clone https://github.com/guangxiangdebizi/FinanceMCP.git
  cd FinanceMCP

• If you do not have Git installed: Download the project files as a ZIP archive, extract them into a folder named FinanceMCP, and then navigate to this folder using a terminal.

2. Install Dependencies

After navigating to the root directory (FinanceMCP) of the project, open a terminal and run the following command to install the required Node.js packages:

bash
npm install

This command reads the package.json file and downloads all the necessary libraries into the node_modules folder.

3. Configure the MCP Server

The server needs to be registered with your MCP client (e.g., Cline). This is typically done through a settings file in the client.

• Locate the settings file for your MCP client. For Cline, the path is usually:

  • Windows: C:\Users\<Your Username>\AppData\Roaming\Code\User\globalStorage\sauridwo.claude-dev\cline_mcp_settings.json* macOS: ~/Library/Application Support/Code/User/globalStorage/sauridwo.claude-dev/cline_mcp_settings.json

• Linux: ~/.config/Code/User/globalStorage/sauridwo.claude-dev/cline_mcp_settings.json
  (The exact path may vary slightly depending on your setup and Cline version.)

• Open cline_mcp_settings.json with a text editor.

• Add or update the configuration for finance-data-server. The configuration should look like this:

json
{
"mcpServers": {
"finance-data-server": { // You can name it anything, just avoid spaces
"url": "http://localhost:3100/sse", // Must point to /sse
"type": "sse", // Use type for VS Code Cline ≥3.14
"disabled": false, // Required! Otherwise, validation will fail
"autoApprove": [
"finance_news",
"stock_data",
"index_data",
"macro_econ",
"create_note"
]
}
}
}

Key Configuration Details:

• "finance-data-server": This is the name you will use to reference the server in Cline.
• "url": The address where your MCP server will run. http://localhost:3100/sse is a common default setting. Port 3100 should match the port your Node.js server is listening on (if using Supergateway).
• "transport": Set to "sse" (Server-Sent Events), which is the recommended communication method. If you are not using Supergateway but running node build/index.js directly, this should be "stdio", and the url field should be changed to command with the value being C:/path/to/FinanceMCP/build/index.js (adjust according to your actual path).
• "autoapprove": A list of tool names that Cline can use from this server without explicitly requesting permission each time.

Image Description: An example of the finance-data-server configuration in cline_mcp_settings.json (SSE mode).

4. Tushare API Token Configuration

The project uses a unified configuration file (src/config.js) to manage Tushare API settings, including the API Token, server address, and timeout settings. You only need to modify the configuration once in this file, and all tools will automatically use the latest settings.

typescript
// Content of src/config.ts
export const TUSHARE_CONFIG = {
/**

• Tushare API Token
• Users only need to modify it once here, and all tools will use this value
  */
  API_TOKEN: "Your Tushare API Token",

/**

• Tushare API server address
  */
  API_URL: "http://api.tushare.pro",

/**

• API request timeout (milliseconds)
  */
  TIMEOUT: 10000
  };

Important Note: If you plan to make this project public, it is strongly recommended not to hard-code the Token directly in the code. A safer approach is to use environment variables or a .env file, and ensure that the .env file is added to .gitignore.

Future Development Plans: In future versions, we plan to support reading Tushare API settings from environment variables and configuration files, making the configuration more flexible and secure.

🚀 Running the Server

After completing all setup and configurations:

1. Build the Project:
   This project uses TypeScript, so you need to compile it into JavaScript:
   bash
   npm run build

   This will compile the TypeScript files in the src directory to the build directory.

2. Start the Server (Recommended to use Supergateway):
   For a better debugging experience and SSE transport support, it is recommended to use Supergateway:
   bash
   npx supergateway --stdio "node build/index.js" --port 3100

   You should see output in the terminal indicating that the server has started and is listening on port 3100.

   Alternatively, Run Directly (stdio mode, requires modifying client configuration):
   bash
   node build/index.js

   If you use this method, make sure that the transport in your cline_mcp_settings.json is set to stdio, and the url field is replaced with command pointing to the path of build/index.js.

   Image Caption: The terminal output shows the server has successfully started and is listening on port 3100 (Supergateway mode).

Keep this terminal window open while using the server. Closing it will stop the server.

💡 Usage Example: Analyzing Ping An Bank

Let's demonstrate how to use this server and Cline to analyze the stock price of Ping An Bank (000001.SZ) through an example.

Step 1: Pose Your Question in Cline

Open your MCP client (Cline), and make sure it is connected to your finance-data-server (or your custom name). Then, you can pose a question like:

"Analyze if the recent price of Ping An Bank will go up, considering the latest news."

Image Caption: Requesting analysis of Ping An Bank's stock price in Cline.

Step 2: Cline Uses the stock_data Tool

Cline will recognize that it needs historical stock data and will use the stock_data tool from your finance-data-server.

• Tool Invocation: Cline will send a request to your server to use the stock_data tool.
  

  Image Caption: Parameters passed to the stock_data tool (e.g., stock code, date range).

• Server Response: Your server will fetch the historical stock data via the Tushare API and send it back to Cline.
  

  Image Caption: Historical stock data of Ping An Bank returned by the server.

Step 3: Cline Uses the finance_news Tool

Next, Cline will determine that it needs recent financial news and will use the finance_news tool.

• Tool Invocation: Cline will request the latest news from your server.
  

  Image Caption: Parameters passed to the finance_news tool (e.g., number of news items, sources).

• Server Response: Your server will fetch the latest financial news via the Tushare API and return it to Cline.
  

  Image Caption: Recent financial news articles returned by the server.

Step 4: Cline Generates the Analysis Report

Combining the historical stock data and recent news, Cline will synthesize this information to provide an analysis and forecast.

Image Caption: Final analysis of Ping An Bank's stock price generated by Cline based on MCP server data.

This step-by-step process demonstrates how your MCP server acts as a bridge, providing the specific real-time data needed for the language model to perform complex tasks via Tushare.

Querying Macroeconomic Data

You can also use the macro_econ tool to query macroeconomic data, such as Gross Domestic Product (GDP), Consumer Price Index (CPI), etc.

"Query the GDP data for the last few years and analyze its trend."

Cline will recognize the need for macroeconomic data and use the macro_econ tool.

• Tool Invocation: Cline will send a request to your server to use the macro_econ tool.
  json
  {
  "indicator": "gdp", // Optional: shibor, lpr, gdp, cpi, ppi
  "start_date": "20180101",
  "end_date": "20231231"
  }

• Server Response: Your server will fetch the GDP data via the Tushare API and send it back to Cline, which will then analyze the data, identifying economic growth trends and influencing factors.

🔍 Troubleshooting

• Server Fails to Start:
  • Check the error messages in the terminal when running npm start or node build/index.js (or via Supergateway).
  • Ensure all dependencies are installed (npm install).
  • If using Supergateway, ensure the port (e.g., 3100) is not occupied by another application.
• Cline Cannot Connect to the Server:* Verify that the server configuration in cline_mcp_settings.json (url and transport, or command and transport) is correct and matches how your server is running.
• Check your firewall settings to ensure it is not blocking connections to the server port (if applicable).
• Ensure that your server is running (the terminal window is open and shows it is listening or related logs).
• Tool Not Working / Errors in Cline:
  • When Cline attempts to use a tool, check the server logs (in the terminal window where the server is running) for error messages, especially those related to the Tushare API.
  • Verify that your Tushare API Token is valid and has the necessary permissions for the required interfaces.
  • Check if the parameters passed to the tool meet the requirements of the Tushare API.
• "Module not found" Error:
  • This usually means a dependency is missing or not properly installed. Try running npm install again. If it's a specific file within the project, check whether the build process (npm run build) completed successfully and if the file path is correct.
• Tushare API Errors:
  • Carefully read the specific error messages from the Tushare API in the server logs. Common errors may include invalid Token, incorrect parameters, too high request frequency, or lack of permission for the corresponding data interface. Refer to the Tushare API Documentation for troubleshooting.

🚀 Future Expansion Directions

This project has great potential for development! Here are some ideas for future enhancements:

1. Add Data Visualization Features

• Description: Integrate chart libraries (e.g., Chart.js, D3.js, or server-side image generation) to allow tools to return visual representations of data, such as stock price charts, trend lines, or sentiment analysis charts.
• Benefits: Visualization can make complex data easier to understand at a glance for users (and AI).
• Implementation Ideas:
  • Create a new tool, e.g., get_stock_chart_image.
  • This tool will accept stock codes and date ranges as inputs.
  • The server side will generate chart images (e.g., in PNG or SVG format) using a library.
  • If the server can host static files, return the image as a base64 encoded string or a publicly accessible URL.

2. Intelligent Data Retrieval for Specific Analysis

• Description: When analyzing a specific stock (e.g., Ping An Bank) or industry, prioritize obtaining data highly relevant to that entity. This means going beyond general news to find company-specific announcements, industry reports, competitor news, and related macroeconomic indicators (many of which can be obtained through the Tushare API).
• Benefits: By focusing on the most impactful information, provide more targeted and accurate analysis.
• Implementation Ideas:
  • Modify existing tools or create new ones (e.g., get_company_announcements, get_industry_analysis) to utilize more interfaces provided by Tushare.
  • These tools will accept company stock codes or industry keywords.
  • The server will query the corresponding Tushare API interfaces.
  • Before returning the data to the LLM, preliminary processing or filtering might be done on the server side.

3. Sentiment Analysis Tool

• Description: Add a tool to perform sentiment analysis on a given set of news articles or financial texts.
• Benefits: Can quickly measure market or public sentiment towards a particular stock or event, which is a useful factor in financial analysis.
• Implementation Ideas:
  • Create a new tool, e.g., analyze_news_sentiment.
  • This tool can accept lists of news headlines/summaries (e.g., obtained from the finance_news tool).
  • The server side will use NLP libraries (e.g., TensorFlow.js, Brain.js, or call an external NLP service) to calculate sentiment scores.
  • Return aggregated sentiment or individual scores.

4. Expand Tushare Data Sources

• Description: Integrate more diverse financial data provided by the Tushare API, such as financial statements, fund data, futures, options, etc.
• Benefits: Provide a richer dataset for more comprehensive analysis.
• Implementation Ideas:
  • Create new tools based on the Tushare Data Interface Documentation.* For example, add tools like get_financial_statement (to obtain financial statements) and get_fund_nav (to get fund net asset values).

5. Real-time Data Streams (Advanced)

• Description: For certain tools, implement real-time data streaming functionality, rather than just a request-response model (Tushare itself may not directly support real-time streaming for all data, but high-frequency polling can be simulated).
• Benefits: Allows monitoring of real-time market changes or news updates.
• Implementation Ideas:
  • Explore using WebSockets or enhanced SSE for continuous data feeds in tools such as monitor_stock_price or stream_breaking_news.
  • This will require careful management of connections and adherence to Tushare API call frequency limits.

6. Expanding Macroeconomic Data Analysis

• Description: Further expand the macroeconomic data tools by adding more economic indicators and analysis features, such as unemployment rates, interest rates, money supply, etc.
• Benefits: Provides users with a more comprehensive macroeconomic perspective, aiding in understanding the broader market environment.
• Implementation Ideas:
  • Expand the existing macro_econ tool to support additional economic indicators.
  • Add correlation analysis features between indicators, such as the relationship between CPI and GDP growth.
  • Integrate international market data to provide cross-market comparative analysis.

🤝 Contributing Code

We welcome code contributions! If you have suggestions for improvements, ideas for new features, or bug fixes, feel free to:

1. Fork this repository: https://github.com/guangxiangdebizi/FinanceMCP/
2. Create a new branch for your feature (git checkout -b feature/your-feature-name).
3. Make your changes.
4. Commit your changes (git commit -m "Add some amazing feature").
5. Push the branch to the remote repository (git push origin feature/your-feature-name).
6. Open a Pull Request.

Please ensure that tests are updated appropriately.

📜 License

This project is released under the MIT License.