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

<video src="https://github.com/quantabox/fyers-mcp-server/assets/fyers-mcp.mp4" width ="300"/>

✨ 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

🛠️ 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

🚧 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

1. Fork the repository
2. Create feature branch: git checkout -b feature/new-tool
3. Add MCP tool: Use @mcp.tool() decorator
4. Test with Claude Desktop
5. 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.

🔗 Links

• Fyers API Documentation
• MCP Protocol Specification
• Claude Desktop
• Issues & Support

📊 Status

• Current Version: 1.0.0
• API Compatibility: Fyers API v3.1.7
• Python Support: 3.10+
• Tools Available: 11/11 ✅
• Production Ready: Yes ✅

🚀 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

1. 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

2. Configure Environment:

   Copy

   cp .env.example .env

   Edit .env file:

   Copy

   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

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

📖 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