Kite MCP Server + OneApp Portfolio Manager

This repository contains two integrated systems:

1. Kite MCP Server: A Model Context Protocol (MCP) server for Zerodha Kite Connect trading APIs
2. OneApp Portfolio Manager: A multi-account portfolio management web application with XIRR tracking

🚀 Quick Start - MCP | 📖 MCP Usage Examples | 🎯 Portfolio App Guide | 📊 Project Status

---

🎉 NEW: OneApp Portfolio Manager

A comprehensive portfolio management system for tracking multiple Zerodha accounts with historical data import and XIRR calculations.

Features

• 📊 Multi-Account Support: Manage 3+ Zerodha accounts in one place
• 📥 CSV Import: Upload Tradebook and Ledger data (5+ years)
• 💰 XIRR Tracking: Calculate annualized returns at portfolio and stock level
• 🔄 Consolidated & Individual Views: Toggle between all accounts or specific ones
• 📈 Holdings Analysis: Detailed P&L and performance metrics per stock
• 🎨 Modern UI: Clean, responsive interface with data privacy toggle

Quick Start (Portfolio App)

# Start DDEV environment
ddev start

# Access the application
open https://oneapp.ddev.site

For detailed setup instructions: See GETTING_STARTED.md

Complete implementation details: See PROJECT_STATUS.md

---

Kite MCP Server

Features

• 🔐 Authentication: Secure login flow with API key and access token management
• 📊 Market Data: Real-time quotes, OHLC, LTP, and historical data
• 📈 Trading: Place, modify, and cancel orders (Regular, AMO, CO, Iceberg, Auction)
• 💼 Portfolio: View holdings, positions, and mutual fund holdings
• 🎯 GTT Orders: Place and manage Good Till Triggered orders
• 🔍 Instrument Search: Search and filter trading instruments
• 📉 Order Management: Track order history and trades

Installation

Prerequisites

• Node.js v18.0.0 or higher
• A Zerodha Kite Connect account with API access
• API Key and API Secret from Kite Connect Developer Console

Setup

1. Clone this repository:

git clone <repository-url>
cd oneapp

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Test the installation:

npm test

You should see: "✅ SUCCESS! MCP Server started correctly."

Configuration

For Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kite": {
      "command": "node",
      "args": ["/absolute/path/to/oneapp/dist/index.js"]
    }
  }
}

For Other MCP Clients

Configure your MCP client to run:

node /path/to/oneapp/dist/index.js

Usage

1. Authentication

First, authenticate with Kite Connect:

Use the login tool with your API key and API secret

The server will return a login URL. Click on it to authorize the application. After authorization, you'll be redirected to a URL containing a request_token parameter.

Use the generate_session tool with the request_token

This will complete the authentication process and store your access token locally in ~/.kite-mcp-credentials.json.

2. Available Tools

Once authenticated, you can use any of the following tools:

Profile & Account

• get_profile: Get user profile information
• get_margins: Get account margin details

Trading

• place_order: Place a new order
• modify_order: Modify an existing order
• cancel_order: Cancel an order
• get_orders: Get all orders
• get_order_history: Get order history for a specific order
• get_order_trades: Get trades for a specific order

Portfolio

• get_positions: Get current positions
• get_holdings: Get holdings
• get_mf_holdings: Get mutual fund holdings
• get_trades: Get trade history

Market Data

• search_instruments: Search for trading instruments
• get_quotes: Get detailed quotes for instruments
• get_ohlc: Get OHLC data
• get_ltp: Get last traded price
• get_historical_data: Get historical candle data

GTT Orders

• place_gtt_order: Place a GTT order
• modify_gtt_order: Modify a GTT order
• delete_gtt_order: Delete a GTT order
• get_gtts: Get all active GTT orders

Example Conversations

Example 1: Check Profile and Margins

User: What's my profile information?
Assistant: [Uses get_profile tool]

User: How much margin do I have?
Assistant: [Uses get_margins tool]

Example 2: Place a Market Order

User: Buy 10 shares of INFY at market price
Assistant: [Uses place_order tool with parameters:
  - variety: "regular"
  - exchange: "NSE"
  - tradingsymbol: "INFY"
  - transaction_type: "BUY"
  - quantity: 10
  - product: "CNC"
  - order_type: "MARKET"
]

Example 3: Get Market Data

User: What's the current price of Reliance?
Assistant: [Uses search_instruments to find the instrument, then get_ltp]

User: Show me the OHLC data for TCS
Assistant: [Uses get_ohlc tool with instruments: ["NSE:TCS"]]

Example 4: View Positions

User: What positions do I have open?
Assistant: [Uses get_positions tool]

User: Show me my holdings
Assistant: [Uses get_holdings tool]

Security

• Credentials Storage: API keys and access tokens are stored locally in ~/.kite-mcp-credentials.json
• Never commit credentials: The .gitignore file is configured to exclude credentials
• API Security: Follow Zerodha's security best practices for API usage

Development

Build

npm run build

Watch Mode

npm run dev

Project Structure

oneapp/                   # Root project directory
├── equity/               # Next.js portfolio management app
│   ├── app/              # Next.js app directory
│   ├── lib/              # Library files
│   ├── components/       # React components
│   └── package.json      # Next.js app dependencies
├── src/                  # MCP server source code
│   ├── index.ts          # Main MCP server implementation
│   └── config.ts         # Configuration helpers
├── dist/                 # Compiled JavaScript (generated, gitignored)
├── .ddev/                # DDEV configuration
├── docs/                 # Documentation
├── documentation/        # Additional documentation
├── package.json          # MCP server dependencies
├── tsconfig.json         # TypeScript configuration
└── README.md

API Reference

This server wraps the official kiteconnectjs library. For detailed API documentation, refer to:

• Kite Connect API Documentation
• kiteconnectjs TypeScript Documentation

Troubleshooting

"Not authenticated" Error

If you see this error, you need to authenticate:

1. Call the login tool with your API key and secret
2. Follow the login URL
3. Call generate_session with the request token

Session Expired

Kite Connect access tokens are valid for the entire trading day. If your session expires:

1. Get a new request token by visiting the login URL
2. Call generate_session with the new request token

API Rate Limits

Kite Connect has rate limits:

• 3 requests per second
• Some endpoints have specific limits

The server does not implement rate limiting, so be mindful of your request frequency.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Disclaimer

This is an unofficial MCP server for Kite Connect. Use at your own risk. Always test with small amounts and paper trading before using real money. The authors are not responsible for any trading losses.

Support

For Kite Connect API issues, contact Zerodha Support

For MCP server issues, please open an issue on this repository.