MCP 服务器

Fyers MCP Server

Enables Claude to interact with the Fyers trading platform for portfolio management, order placement, market data retrieval, and automated OAuth authentication for Indian stock markets.

README

Fyers MCP Server

MCP (Model Context Protocol) server for Fyers API v3 with automated OAuth authentication

A comprehensive MCP server that enables Claude Desktop to interact with Fyers trading platform through a secure, automated authentication flow. Supports all major trading operations including portfolio management, order placement, and real-time market data.

🎬 Demo

✨ Features

🔐 Smart Authentication

One-click OAuth flow with automatic browser handling
Persistent token storage in .env file
Auto-refresh capabilities with session management

📊 Complete Trading Toolkit

Portfolio Management: Holdings, positions, funds, profile
Order Management: Place, modify, cancel orders
Market Data: Real-time quotes for multiple symbols
Order History: Complete order and trade book

🚀 Production Ready

Full error handling with detailed error messages
Type safety with parameter validation
Comprehensive logging for debugging
Claude Desktop integration with simple configuration

🚀 Quick Start

Prerequisites

Python 3.10 or higher
Claude Desktop installed
Fyers Trading Account with API access

1. Installation

# Clone the repository
git clone https://github.com/quantabox/fyers-mcp-server.git
cd fyers-mcp-server

# Install dependencies using uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Or install with pip
pip install .

2. Get Fyers API Credentials

Create Fyers API App:
- Visit Fyers API Dashboard
- Create a new app with redirect URI: http://localhost:8080/
- Note down your App ID and Secret Key

Configure Environment:

cp .env.example .env

Edit .env file:

FYERS_CLIENT_ID=YOUR_APP_ID-100     # e.g., ABC123XYZ-100
FYERS_SECRET_KEY=YOUR_SECRET_KEY    # Secret from Fyers app
FYERS_REDIRECT_URI=http://localhost:8080/

3. Configure Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fyers-mcp-server": {
      "command": "uv",
      "args": [
        "run", 
        "--directory",
        "/path/to/fyers-mcp-server",
        "python",
        "fyers_mcp_complete.py"
      ],
      "env": {
        "PYTHONWARNINGS": "ignore"
      }
    }
  }
}

4. First Run

Restart Claude Desktop
Authenticate: In Claude, type: authenticate
Browser will open → Login to Fyers → Automatic token capture
Start trading: All 11 tools are now available!

🛠️ Available Tools

Authentication & Profile

authenticate() - One-click OAuth authentication
check_auth_status() - Verify current authentication
get_profile() - User profile information

Portfolio & Funds

get_funds() - Account balance and margin details
get_holdings() - Portfolio holdings with P&L
get_positions() - Current trading positions

Orders & Trading

place_order(symbol, quantity, order_type, side, ...) - Place new orders
modify_order(order_id, quantity, limit_price, ...) - Modify existing orders
cancel_order(order_id) - Cancel pending orders
get_orders() - Order history and status

Market Data

get_quotes(symbols) - Real-time quotes for multiple symbols

📖 Usage Examples

Portfolio Analysis

# Check account balance
get_funds()

# View all holdings with P&L
get_holdings()

# Check current positions
get_positions()

Order Management

# Place a market order
place_order("NSE:SBIN-EQ", 10, "MARKET", "BUY")

# Place a limit order
place_order("NSE:RELIANCE-EQ", 5, "LIMIT", "BUY", limit_price=2500)

# Modify an order
modify_order("ORDER_ID", quantity=15, limit_price=2550)

# Cancel an order
cancel_order("ORDER_ID")

Market Data

# Get live quotes
get_quotes("NSE:SBIN-EQ,NSE:RELIANCE-EQ,NSE:TCS-EQ")

🔧 Configuration Options

Order Types

MARKET - Market order (immediate execution)
LIMIT - Limit order (execute at specific price)
STOP - Stop loss order
STOPLIMIT - Stop limit order

Product Types

MARGIN - Margin trading (intraday with leverage)
CNC - Cash and Carry (delivery)
INTRADAY - Intraday trading
BO - Bracket Order
CO - Cover Order

Validity Options

DAY - Valid for current trading day
IOC - Immediate or Cancel
GTD - Good Till Date

🐛 Troubleshooting

Common Issues

1. Authentication Failed

# Check credentials in .env file
cat .env | grep FYERS

# Verify app configuration at https://myapi.fyers.in/dashboard/

2. Claude Desktop Connection Issues

# Test MCP server directly
cd /path/to/fyers-mcp-server
uv run python fyers_mcp_complete.py

# Check Claude Desktop logs (macOS)
tail -f ~/Library/Logs/Claude/mcp.log

3. Order Placement Errors

Verify symbol format: NSE:SYMBOL-EQ for equity
Check market hours (9:15 AM - 3:30 PM IST)
Ensure sufficient funds/margin

Debug Mode

Enable detailed logging:

export LOG_LEVEL=DEBUG
uv run python fyers_mcp_complete.py

🚧 Development

Project Structure

fyers-mcp-server/
├── fyers_mcp_complete.py    # Main MCP server
├── pyproject.toml          # Dependencies
├── .env.example           # Environment template
├── claude_config.json     # Claude Desktop config
└── README.md             # This file

Adding New Features

Fork the repository
Create feature branch: git checkout -b feature/new-tool
Add MCP tool: Use @mcp.tool() decorator
Test with Claude Desktop
Submit pull request

Testing

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Type checking
uv run mypy fyers_mcp_complete.py

📋 API Reference

Authentication Flow

graph TD
    A[Claude: authenticate] --> B[Generate Auth URL]
    B --> C[Open Browser]
    C --> D[User Login]
    D --> E[Auth Code Capture]
    E --> F[Exchange for Token]
    F --> G[Store in .env]
    G --> H[Ready for Trading]

Error Handling

All functions return standardized responses:

✅ Success: Clear confirmation with relevant data
❌ Error: Detailed error message with troubleshooting hints

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Areas for Contribution

WebSocket real-time data streaming
Advanced order types (OCO, Iceberg)
Portfolio analytics and reporting
Options chain analysis tools
Risk management features

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This software is for educational and development purposes. Trading involves financial risk. Users are responsible for their trading decisions and should thoroughly test in demo environments before live trading.