mcp_zhitou_server

mcp_zhitou_server

mcp_zhitou_server

✨ Zhitou HS Data MCP Server（Python 版）✨

Cursor や Cline などの AI エージェントに、中国A株市場のリアルタイムデータを提供します！🚀

コーダーの皆さん、こんにちは！👋 PGFA です！Zhitou HS Data MCP Server プロジェクトへようこそ！

このプロジェクトは、Python で書かれた モデルコンテキストプロトコル（MCP） サーバーの実装です。中心的な役割は、AI エージェント（話題の Cursor エディターや Cline コマンドラインアシスタントなど）と 智兔数服の沪深データ API (https://www.zhituapi.com/hsstockapi.html) をつなぐ橋渡しをすることです 🌉。

簡単に言うと、これを使えば、AI エージェントのチャット欄で自然言語を使って、リアルタイムのA株銘柄リストや企業情報、資金の流れなどをAIに直接問い合わせられます。もう手作業で調べる必要はありません！とても便利で、効率もアップします！📈

🌟 主な機能

• MCP 標準の実装: 標準入出力（stdio）を介して、MCP 互換クライアントと JSON-RPC 通信を行います。
• Zhitou API に直接接続: 智兔数服が提供する豊富な沪深市場データ API をシームレスに利用できます。
• Python で実装: コードは簡潔で分かりやすく、二次開発や拡張も簡単です。（Python は最高！🐍）
• すぐに使える: 分かりやすい設定ガイドに従って、Cursor や Cline で簡単に有効化できます。
• ツールとしてラップ: よく使う Zhitou API を MCP ツールとしてラップし、AI から簡単に呼び出せるようにしています。
• 基本的なログ記録とエラー処理: デバッグに便利な、必要なログ記録と例外処理を備えています。

🛠️ クイックスタート

PGFA のペースに合わせて、3ステップで設定しましょう！

1. 環境の準備（Prerequisites）

• Python: Python がインストールされていることを確認してください（3.8 以降を推奨）。
• Requests ライブラリ: API の呼び出しに使用します。ターミナル／コマンドラインを開いて、次を実行してください：

  pip install requests
  

• 智兔 API Token: 智兔数服 (https://www.zhituapi.com/) のアカウントを取得し、API Token を入手する必要があります。
• MCP クライアント: Cursor (https://cursor.sh/) または Cline (https://github.com/SaudriData/cline) をインストールします。

2. コードの取得と Token の設定

• このリポジトリにある唯一のファイル、mcp_zhitou_server.py をダウンロードします

• 🔥【非常に重要】🔥 API Token を設定します： メインスクリプトファイル mcp_zhitou_server.py（または任意の名前を付けたメインファイル）を開き、次の行を探します：

  # 🔥🔥🔥【必ず有効なご自身の Token に置き換えてください！テスト用 Token には制限があります！】🔥🔥🔥
  ZHITU_TOKEN = "ZHITU_TOKEN_LIMIT_TEST"
  

  "ZHITU_TOKEN_LIMIT_TEST" を、智兔数服で取得したご自身の実際の API Token に置き換えてください！置き換えないと、サービスは正常に動作しません！

3. MCP クライアントの設定

使用するクライアントに応じて設定してください：

• Cline を使用する場合：

  1. Cline（スタンドアロン版または VS Code 拡張機能）を開きます。
  2. 設定を開き、MCP Servers の管理画面を見つけます。
  3. 新しい MCP Server を追加します。
  4. Name: 任意の名前を入力します。たとえば Zhitou_HS_API。
  5. Command: Python インタープリターの完全なパスと、保存したスクリプトの絶対パスを入力します。
     • Mac/Linux の例: /usr/local/bin/python3 /path/to/your/project/mcp_zhitou_server.py
     • Windows の例: C:\Python311\python.exe C:\Users\PGFA\project\mcp_zhitou_server.py（実際の環境に合わせてパスを変更してください！）
  6. 設定を保存します。Cline を起動すると、この Server が接続状態になっているはずです。

• Cursor を使用する場合：

  1. プロジェクトのルートディレクトリに、.cursor という名前のフォルダーを作成します（まだ存在しない場合）。

  2. .cursor フォルダー内に、mcp.json という名前のファイルを作成します。

  3. 次の JSON を貼り付け、args 内のスクリプトパスを実際の絶対パスに変更します：

     {
       "mcpServers": {
         "zhitou_hs": { // サーバーの一意な識別子です。自由に設定できます
           "command": "python", // または python3
           "args": ["/path/to/your/project/mcp_zhitou_server.py"], // ⚠️⚠️⚠️ スクリプトの実際のパスに変更してください！
           // "workingDirectory": "/path/to/your/project/", // 任意ですが、設定をおすすめします
           "tools": [
             // 実装したツールをここで宣言しておくと、エージェントが見つけやすくなります
             {"name": "get_stock_list", "description": "基本的なA株銘柄リスト（コード、名称、取引所）を取得します。"},
             {"name": "get_new_stock_calendar", "description": "新規株式公開カレンダー（申込情報、上場日など）を取得します。"},
             {"name": "get_company_profile", "description": "指定した銘柄コードの上場企業プロフィールを取得します。", "parameters": {"stock_code": {"type":"string", "description": "銘柄コード。例：'000001'"}}},
             {"name": "get_capital_daily_trend", "description": "指定した銘柄コードの日次資金流入傾向（過去10年間）を取得します。", "parameters": {"stock_code": {"type":"string"}}},
             {"name": "get_all_announcements", "description": "指定した銘柄コードの過去の全公告リストを取得します。", "parameters": {"stock_code": {"type":"string"}}}
             // ... ツールを追加した場合は、ここでも宣言してください ...
           ]
         }
       }
     }
     

  4. mcp.json ファイルを保存します。Cursor を再起動するか、プロジェクト設定を再読み込みします。

4. 使ってみましょう！🎉

Cursor または Cline のチャットウィンドウを開き、自然言語で AI に話しかけて、定義したツールを呼び出してみましょう！

• "get_stock_list ツールを使って、最新の銘柄リストを確認してください。"
• "000001 の企業プロフィールを、get_company_profile ツールを使って調べてください。"
• "今日の新規株式公開カレンダーは？"（AI は get_new_stock_calendar を選択するはずです）
• "銘柄 600519 の最近の公告をすべて確認してください。"（AI は get_all_announcements を選択するはずです）

AI の返答とターミナルのログを確認して、AI に作業を手伝ってもらう楽しさを味わってください！😉

🔧 可用工具列表 (Tools Available)

当前已实现的 MCP 工具 (对应 Python 函数)：

• get_stock_list: 获取基础 A 股股票列表 (代码, 名称, 交易所)。
• get_new_stock_calendar: 获取新股日历 (申购信息, 上市日期等)。
• get_company_profile: 获取指定股票代码的上市公司简介。(需要 stock_code 参数)
• get_capital_daily_trend: 获取指定股票代码的每日资金流入趋势 (近十年)。(需要 stock_code 参数)
• get_all_announcements: 获取指定股票代码的历史所有公告列表。(需要 stock_code 参数)
• (欢迎添加更多工具！)

🚀 如何扩展？(Adding More Tools)

想让你的 AI 助手更强大？完全 OK！

1. 查阅智兔 API 文档: 找到你想添加功能的 API 端点。
2. 编写 Python 函数: 在 mcp_zhitou_server.py 中，仿照现有的工具函数，编写一个新的函数来调用这个 API，记得处理好参数和返回值。给函数写上清晰的 docstring 哦！
3. 注册工具: 在 TOOLS 字典里，添加一行，把新的工具名和你刚写的函数关联起来。
4. (可选) 更新客户端配置: 如果你的客户端配置 (如 Cursor 的 mcp.json) 需要显式声明工具列表，记得把新工具加进去。
5. 重启你的 MCP 服务（通常客户端会自动重启或重新连接）。

搞定！你的 AI 又解锁了新技能！😎

📜 许可证 (License)

本项目采用 MIT 许可证。

🙏 致谢 (Acknowledgements)

• 感谢 智兔数服 提供稳定易用的沪深数据 API。
• 感谢 Anthropic 提出 MCP 协议，开启了 AI Agent 的新时代。
• 感谢屏幕前的你！点个 Star ⭐ 支持一下 PGFA 吧！

---

希望这份 README 对你有帮助！快去试试看，让你的 AI 动起来吧！有问题欢迎在 Issues 区提出。Have Fun Coding! 💖