tqsdk-mcp-server

# TqSDK MCP Server TqSDK MCP Server - Futures Quant Trading with AI Assistants [](https://www.python.org/downloads/) [](LICENSE) [](https://modelcontextprotocol.io/) ## Feature Introduction Integrate [TqSDK](https://github.com/shinnytech/tqsdk-python) with MCP protocol, enabling AI tools like Claude, WorkBuddy, and Cursor to directly interact with futures market data, account management, and trading. ### Supported Operations | Tool | Function | Requires Account | |------|----------|------------------| | `tqsd_get_quote` | Get Real-time Quotes | ❌ | | `tqsd_get_klines` | Get K-line Data | ❌ | | `tqsd_search_instruments` | Search Instrument Codes | ❌ | | `tqsd_get_account` | Query Account Funds | ✅ | | `tqsd_get_positions` | Query Positions | ✅ | | `tqsd_get_orders` | Query Order Details | ✅ | | `tqsd_get_trades` | Query Trade Records | ✅ | | `tqsd_place_order` | Place Order (Limit/Market) | ✅ | | `tqsd_cancel_order` | Cancel Order | ✅ | | `tqsd_close_position` | Close Position | ✅ | ### Three Operation Modes | Mode | TRADE_MODE | Description | |------|-----------|------------| | Quote Only | `quote_only` | No account needed, only quote access | | Simulated Trading | `simulate` | Requires TqSDK account, simulated funds | | Live Trading | `real` | Requires fast trading terminal and live account | ## Quick Start ### 1. Installation ```bash # Clone the project git clone https://github.com/your-username/tqsdk-mcp-server.git cd tqsdk-mcp-server # Install dependencies pip install -e . ``` ### 2. Configuration Copy environment variable template: ```bash cp .env.example .env ``` Edit `.env`: ```env # Only required for non-quote modes TQ_USERNAME=your_tq_username TQ_PASSWORD=your_tq_password # Mode selection TRADE_MODE=simulate # Safety switch: true to prohibit all trading operations READ_ONLY=false ``` ### 3. Register TqSDK Account (Optional) For simulated trading, register an account on [TqSDK website](https://www.shinnytech.com). ### 4. Configure MCP Client #### WorkBuddy Edit `~/.workbuddy/mcp.json`: ```json { "mcpServers": { "tqsdk": { "command": "path/to/tqsdk-mcp-server/run.bat", "env": { "TQ_USERNAME": "your_username", "TQ_PASSWORD": "your_password", "TRADE_MODE": "simulate" } } } } ``` #### Claude Desktop Edit `claude_desktop_config.json`: ```json { "mcpServers": { "tqsdk": { "command": "python", "args": ["-m", "tqsdk_mcp.server"], "env": { "TQ_USERNAME": "your_username", "TQ_PASSWORD": "your_password", "TRADE_MODE": "simulate" } } } } ``` #### Cursor Edit `~/.cursor/mcp.json`: ```json { "mcpServers": { "tqsdk": { "command": "python", "args": ["-m", "tqsdk_mcp.server"], "env": { "TQ_USERNAME": "your_username", "TQ_PASSWORD": "your_password", "TRADE_MODE": "simulate" } } } } ``` ## Example Usage ### Search Instrument ``` Search for main SHFE copper contract ↓ Call tqsd_search_instruments(keyword="SHFE copper") ``` ### View Quotes ``` Check real-time price of SHFE rb2501 ↓ Call tqsd_get_quote(instrument="SHFE.rb2501") ``` ### Place Order ``` Buy 1 hand of SHFE rb2501 at limit price 3800 ↓ Call tqsd_place_order(instrument="SHFE.rb2501", direction="BUY", offset="OPEN", volume=1, price=3800) ``` ### Query Positions ``` What's my current position? ↓ Call tqsd_get_positions() ``` ### Close Position ``` Close all long positions of SHFE rb2501 ↓ Call tqsd_close_position(instrument="SHFE.rb2501", direction="BUY") ``` ## Supported Exchanges | Exchange Code | Name | |-----------|------| | SHFE | Shanghai Futures Exchange | | DCE | Dalian Commodity Exchange | | CZCE | Zhengzhou Commodity Exchange | | CFFEX | China Financial Futures Exchange | | INE | Shanghai International Energy Exchange | | GFEX | Guangzhou Futures Exchange | ## Security Warning > ⚠️ **Important**: Before live trading, thoroughly test in simulated environment. Trading carries risks; any financial losses are the user's responsibility. - **Do not commit `.env` file to Git** - Always start testing with `READ_ONLY=true` - Verify strategies in simulated environment - Set stop-loss for live trading - Store API keys and passwords securely (e.g., Vaultwarden) ## Project Structure ``` tqsdk-mcp-server/ ├── src/ │ └── tqsdk_mcp/ │ ├── __init__.py │ ├── server.py # MCP server main logic │ └── config.py # Configuration management ├── pyproject.toml ├── README.md ├── LICENSE ├── .env.example └── .gitignore ``` ## Dependencies - Python >= 3.10 - [tqsdk](https://github.com/shinnytech/tqsdk-python) >= 3.10.0 - [mcp](https://github.com/modelcontextprotocol/python-sdk) >= 1.6.0 ## License MIT License - See [LICENSE](LICENSE) ## Disclaimer This software is for educational and research purposes only; it does not constitute investment advice. Futures trading carries high risks and may result in total loss of principal. Users are responsible for all trading risks.