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: Get 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 bundled 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 the Git source.
   • 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 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 and instead running node build/index.js directly, set this to "stdio", and change the url field 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 needing explicit permission each time.

Image description: Example configuration of finance-data-server 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 more secure 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 Client Configuration Update):
   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 that the server has successfully started and is listening on port 3100 (Supergateway mode).

Keep this terminal window open during the use of 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: Ask 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 ask a question like:

"Analyze whether the recent price of Ping An Bank will rise, taking into account the latest news."

Image Caption: Asking Cline to analyze the stock price of Ping An Bank.

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 the latest 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, source).

• 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 analysis and predictions.

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, obtained through 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 of recent 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 trends in economic growth and influencing factors.

🔍 Troubleshooting

• Server Fails to Start:

  • When running npm start or node build/index.js (or through Supergateway), check for error messages in the terminal.
  • 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).

• Make sure 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 tries 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. Please 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. Adding Data Visualization Features

• Description: Integrate chart libraries (such as 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, such as get_stock_chart_image.
  • This tool will accept stock codes and date ranges as input.
  • 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 leverage 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 occur 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, such as analyze_news_sentiment.
  • This tool could accept a list of news headlines/summaries (e.g., obtained from the finance_news tool).
  • The server side will use an NLP library (such as TensorFlow.js, Brain.js, or call an external NLP service) to calculate sentiment scores.
  • Return aggregated sentiment or individual scores.

4. Expanding 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 richer datasets for more comprehensive analysis.
• Implementation Ideas:
  • Create new tools based on the Tushare data interface documentation.* For example, add tools such as 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 the use of WebSockets or enhanced SSE for continuous data feeds in tools like 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 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, new feature ideas, 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 as appropriate.

📜 License

This project is released under the MIT License.