{"id":51469981,"url":"https://github.com/pdone/xqmcp","last_synced_at":"2026-07-06T16:00:43.385Z","repository":{"id":363714695,"uuid":"1264565665","full_name":"pdone/xqmcp","owner":"pdone","description":"雪球MCP","archived":false,"fork":false,"pushed_at":"2026-06-10T03:21:04.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T05:03:51.787Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://xqmcp.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pdone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-10T02:00:49.000Z","updated_at":"2026-06-10T03:21:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pdone/xqmcp","commit_stats":null,"previous_names":["pdone/xqmcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pdone/xqmcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdone%2Fxqmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdone%2Fxqmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdone%2Fxqmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdone%2Fxqmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pdone","download_url":"https://codeload.github.com/pdone/xqmcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdone%2Fxqmcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35197534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-06T16:00:42.548Z","updated_at":"2026-07-06T16:00:43.358Z","avatar_url":"https://github.com/pdone.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pysnowball MCP Server\n\n基于 [pysnowball](https://pypi.org/project/pysnowball/) 的雪球股票数据服务器，同时支持 **MCP 协议** 和 **REST API**，可一键部署到 Vercel。\n\n## 功能特性\n\n- **51 个 API 接口** - 覆盖实时行情、财务数据、基金、指数等\n- **双协议支持** - MCP 协议 + REST API，满足不同场景需求\n- **多传输方式** - 本地 stdio（推荐）+ 远程 Streamable HTTP（无状态）\n- **本地优先** - stdio 模式无 session 限制，稳定性最佳\n- **Swagger 文档** - 自动生成，开箱即用\n- **API 认证** - 可选的 `x-api-key` 保护\n- **一键部署** - 支持 Vercel Serverless 部署（REST API）\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n### 2. 配置环境变量\n\n```bash\n# 必填：雪球网 token\nexport XUEQIU_TOKEN=your_xueqiu_token\n\n# 可选：API 访问密钥（设置后需要 x-api-key 认证）\nexport API_TOKEN=your_api_key\n```\n\n\u003e **获取雪球 Token：** 登录 [雪球网](https://xueqiu.com) → F12 开发者工具 → Application → Cookies → `xq_a_token`\n\n### 3. 启动服务\n\n```bash\npython server.py\n```\n\n- Swagger UI: http://localhost:8000/docs\n- MCP 端点: http://localhost:8000/mcp (Streamable HTTP)\n\n## 部署到 Vercel\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fpdone%2Fxqmcp)\n\n1. Fork 本项目到你的 GitHub\n2. 在 [Vercel](https://vercel.com) 导入项目\n3. 添加环境变量：\n   - `XUEQIU_TOKEN`（必填）\n   - `API_TOKEN`（可选）\n4. 完成部署\n\n部署后访问 `https://your-project.vercel.app/docs` 查看 Swagger 文档。\n\n\u003e [!NOTE]\n\u003e **Vercel** 部署已启用 MCP 无状态模式（`stateless_http=True`），无需 session 管理，可正常使用 MCP 协议。每个请求独立处理，不依赖会话状态。\n\n## API 使用\n\n### REST API\n\n每个接口都是独立的 POST 请求：\n\n```bash\n# 搜索股票\ncurl -X POST \"https://your-project.vercel.app/api/search_stock\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"q\": \"贵州茅台\"}'\n\n# 获取实时行情（无需认证）\ncurl -X POST \"https://your-project.vercel.app/api/get_quote\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"symbol\": \"SH600519\"}'\n\n# 获取主要指标（需要 XUEQIU_TOKEN）\ncurl -X POST \"https://your-project.vercel.app/api/get_main_indicator\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-api-key: your_api_key\" \\\n  -d '{\"symbol\": \"SH600519\"}'\n```\n\n### MCP 协议\n\n支持两种传输方式：**本地 stdio（推荐）** 和 **远程 Streamable HTTP**。\n\n#### 方式一：本地 stdio（推荐）\n\n本地运行 MCP 服务器，无 session 限制，稳定性最佳。\n\n1. **获取代码**\n   ```bash\n   git clone https://github.com/pdone/xqmcp.git\n   cd xqmcp\n   ```\n\n2. **安装依赖**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **配置环境变量**\n   创建 `.env` 文件或设置系统环境变量：\n   ```bash\n   # 必填：雪球网 token\n   export XUEQIU_TOKEN=your_xueqiu_token\n   \n   # 可选：API 访问密钥\n   export API_TOKEN=your_api_key\n   ```\n\n4. **配置 Claude Desktop (`claude_desktop_config.json`)：**\n   ```json\n   {\n     \"mcpServers\": {\n       \"pysnowball\": {\n         \"command\": \"python\",\n         \"args\": [\"path/to/stdio.py\"],\n         \"env\": {\n           \"XUEQIU_TOKEN\": \"your_xueqiu_token\",\n           \"API_TOKEN\": \"your_api_key\"\n         }\n       }\n     }\n   }\n   ```\n\n5. **或配置 Claude Code CLI：**\n   ```bash\n   claude mcp add pysnowball -- python path/to/stdio.py\n   ```\n\n#### 方式二：远程 Streamable HTTP\n\n使用 HTTP/HTTPS 协议，适合远程访问场景。Vercel 部署已支持无状态模式，可正常使用。\n\n**Claude Desktop (`claude_desktop_config.json`)：**\n```json\n{\n  \"mcpServers\": {\n    \"pysnowball\": {\n      \"url\": \"https://your-project.vercel.app/mcp\",\n      \"headers\": {\n        \"x-api-key\": \"your_api_key\"  // 可选，API_TOKEN 为空时可删除\n      }\n    }\n  }\n}\n```\n\n**Claude Code CLI：**\n```bash\n# 无认证\nclaude mcp add pysnowball --transport http https://your-project.vercel.app/mcp\n\n# 带认证\nclaude mcp add pysnowball --transport http https://your-project.vercel.app/mcp --header \"x-api-key: your_api_key\"\n```\n\n**Streamable HTTP 优势：**\n- 使用标准 HTTP/HTTPS 协议，穿透防火墙和代理\n- 支持双向流式传输\n- 支持会话管理和断线重连\n- 更好的兼容性和稳定性\n\n## 接口分类\n\n| 分类 | 接口数 | 示例接口 |\n|------|--------|----------|\n| 实时行情 | 3 | `get_quote`, `get_pankou`, `get_quote_detail` |\n| 财务数据 | 9 | `get_balance`, `get_income`, `get_cash_flow` |\n| 基本面 | 11 | `get_holders`, `get_top_holders`, `get_bonus` |\n| 资金流向 | 5 | `get_capital_flow`, `get_margin` |\n| 研报数据 | 2 | `get_report`, `get_earningforecast` |\n| 基金数据 | 9 | `get_fund_detail`, `get_fund_nav_history` |\n| 指数数据 | 6 | `get_index_basic_info`, `get_index_weight_top10` |\n| 债券数据 | 1 | `get_convertible_bond` |\n| 港股通 | 2 | `get_northbound_shareholding_sh/sz` |\n| 用户数据 | 2 | `get_watch_list`, `get_watch_stock` |\n| 搜索 | 1 | `search_stock` |\n\n\u003e 完整接口文档请访问 Swagger UI: `/docs`\n\n## 项目结构\n\n```\nxqmcp/\n├── api/\n│   └── index.py          # Vercel 入口 + MCP Streamable HTTP 处理\n├── tools/                # 工具函数（每个模块对应一个分类）\n│   ├── realtime.py       # 实时行情\n│   ├── finance.py        # 财务数据\n│   ├── f10.py            # 基本面\n│   ├── capital.py        # 资金流向\n│   ├── report.py         # 研报数据\n│   ├── fund.py           # 基金数据\n│   ├── index.py          # 指数数据\n│   ├── bond.py           # 债券数据\n│   ├── hkex.py           # 港股通\n│   ├── user.py           # 用户数据\n│   ├── cube.py           # 组合数据（已清空，工具已移除）\n│   └── suggest.py        # 搜索\n├── mcp_server.py         # MCP 服务器核心\n├── stdio.py              # 本地 stdio 模式入口（推荐）\n├── server.py             # FastAPI 服务器 + Swagger\n├── tests/                # 测试脚本\n├── vercel.json           # Vercel 部署配置\n├── requirements.txt      # Python 依赖\n└── runtime.txt           # Python 版本\n```\n\n## 环境变量\n\n| 变量名 | 必填 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `XUEQIU_TOKEN` | 是 | - | 雪球网登录 token |\n| `API_TOKEN` | 否 | 空 | API 访问密钥，设置后启用 `x-api-key` 认证 |\n\n## 技术栈\n\n- [pysnowball](https://pypi.org/project/pysnowball/) - 雪球数据接口\n- [FastAPI](https://fastapi.tiangolo.com/) - REST API 框架\n- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - MCP 协议支持（Streamable HTTP）\n- [Vercel](https://vercel.com) - Serverless 部署平台\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdone%2Fxqmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpdone%2Fxqmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdone%2Fxqmcp/lists"}