Flipkart Seller MCP Server

A high-performance, token-optimized Model Context Protocol (MCP) server for the Flipkart Seller v3 API. Built using Python (FastMCP + Pydantic), this server enables AI agents (Claude Desktop, Antigravity, OpenCode, Cursor, AutoGen) to manage order fulfillment, listing inventory & pricing CRUD, customer returns, ad campaigns, and payout settlements.

---

📚 Table of Contents

• Features
• ⚡ Token Optimization Architecture
• 🔑 How to Get Flipkart Credentials
• Installation & Setup
• 🤖 Guidance for AI Agents
• Available Domain Tools
• 🔮 Future Scope & Roadmap
• Development & Testing
• License

---

Features

• Token-Optimized Architecture: Returns clean, concise Markdown tables (~100–300 tokens) by default, saving up to 90% context tokens for LLM reasoning loops.
• Consolidated Master Domain Tools: Exposes 5 unified master tools (shipments, inventory, returns, ads, financials) with strict action parameters to prevent tool schema clutter in agent prompts.
• Full Catalog & Listings CRUD: Search, create, update details/prices/stock, and deactivate catalog listings.
• Auto OAuth Lifecycle: Proactive OAuth2 client-credentials authentication with 5-minute pre-expiration token auto-refresh.
• Out-of-the-Box Mock Mode: Runs seamlessly in mock mode if API credentials are missing, making development and agent testing instant.

---

⚡ Token Optimization Architecture

flipkart-seller-mcp was architected from the ground up to minimize context token usage for LLM agents:

1. Schema Consolidation (5 Master Tools vs 30+ Micro-Tools): By grouping endpoints into 5 master domain tools (flipkart_manage_shipments, flipkart_manage_inventory, flipkart_manage_returns, flipkart_manage_ads, flipkart_manage_financials), we reduce the tool schema footprint in the agent's system prompt from ~4,000 tokens down to ~500 tokens.
2. detail_level: "summary" Defaulting: Raw API payloads for Flipkart orders/listings can exceed 5,000 tokens per single API call. Every tool defaults to detail_level="summary", extracting only essential columns (e.g. shipmentId, orderId, sku, status, dispatchByDate) formatted into Markdown tables (~100–300 tokens).
3. Pydantic Type Compression: Field annotations and descriptions are written concisely without redundant verbose prose, avoiding schema inflation during agent initialization.
4. Pagination & Output Capping: Responses cap summary listings at 10 items per page by default, preventing unexpected context window overflows.

---

🔑 How to Get Flipkart Credentials

To connect to a live Flipkart Seller Hub account, you need a Client ID and Client Secret.

👉 Read the Step-by-Step Credentials Guide

Quick Overview:

1. Log in to Flipkart Seller Hub.
2. Go to Manage Profile > Developer Access.
3. Create a Self Access Application and enable required scopes (Orders, Listings, Returns, Financials, Ads).
4. Copy your Application ID (FLIPKART_CLIENT_ID) and Application Secret (FLIPKART_CLIENT_SECRET).

---

Installation & Setup

1. Prerequisites

• Python 3.10+
• uv, pip, or npx

2. Environment Setup

Create a .env file in your workspace root:

FLIPKART_CLIENT_ID=your_flipkart_application_id
FLIPKART_CLIENT_SECRET=your_flipkart_application_secret
# Optional: defaults to https://api.flipkart.net
FLIPKART_API_BASE_URL=https://api.flipkart.net

3. Usage with MCP Clients

Claude Desktop / Antigravity / OpenCode Configuration

{
  "mcpServers": {
    "flipkart": {
      "command": "uvx",
      "args": ["flipkart-seller-mcp"],
      "env": {
        "FLIPKART_CLIENT_ID": "your_client_id_here",
        "FLIPKART_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Or via Node/NPM runner:

{
  "mcpServers": {
    "flipkart": {
      "command": "npx",
      "args": ["-y", "flipkart-seller-mcp"],
      "env": {
        "FLIPKART_CLIENT_ID": "your_client_id_here",
        "FLIPKART_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

---

🤖 Guidance for AI Agents

When interacting with flipkart-seller-mcp, follow these best practices for maximum performance and token efficiency:

1. Use action Parameters: Each master tool uses a required action switch (e.g. flipkart_manage_shipments(action="search")). Check the tool docstrings for supported actions.
2. Leverage Token Efficiency (detail_level):
   • detail_level="summary" (Default): Returns a compact Markdown summary table (~100–300 tokens). Ideal for scanning and planning.
   • detail_level="full": Returns the un-truncated raw API JSON response. Use only when deep data extraction is required.
3. Multi-Step Fulfillment Flow:
   • Step 1: flipkart_manage_shipments(action="search", state="APPROVED") to list new orders.
   • Step 2: flipkart_manage_shipments(action="inspect", shipment_ids=["SHIP_ID"]) to view item & SLA details.
   • Step 3: flipkart_manage_shipments(action="mark_rtd", shipment_ids=["SHIP_ID"]) to pack and mark Ready for Dispatch.
   • Step 4: flipkart_manage_shipments(action="get_label", shipment_ids=["SHIP_ID"]) to fetch printable PDF label & invoice.
4. Listings & Inventory CRUD Flow:
   • Use flipkart_manage_inventory(action="create_listing", sku="SKU123", title="...", selling_price=499.0) to create new products.
   • Use update_stock or update_price for quick operational changes.

---

Available Domain Tools

Tool Name	Actions Supported	Primary Description
flipkart_manage_shipments	search, inspect, mark_rtd, get_label, cancel	Order fulfillment, packing, SLA inspection, label & invoice PDF retrieval, cancellations.
flipkart_manage_inventory	search, get_details, update_stock, update_price, create_listing, update_listing, delete_listing	Catalog listings CRUD, warehouse stock updates, MRP and Selling Price management.
flipkart_manage_returns	list_returns, track_rto, approve_return, spf_claim	Customer return requests, courier RTO tracking, return approvals, Seller Protection Fund (SPF) claims.
flipkart_manage_ads	list_campaigns, get_metrics, update_budget, update_bid	Ad campaign performance (PLA/PCA), daily spend, ROAS tracking, budget & bid updates.
flipkart_manage_financials	get_settlements, request_report, download_report	Bank payouts, settlement summaries, tax/sales report generation & download links.

---

🔮 Future Scope & Roadmap

1. Unified Multi-Marketplace Adapter (unified-ecom-mcp): Extraction of FlipkartClient into a unified e-commerce protocol alongside Amazon SP-API, Shopify, and Meesho adapters.
2. AI-Powered SPF Dispute & Claims Assistant: Automated filing of Seller Protection Fund (SPF) claims with AI image verification for wrong/damaged return items.
3. Dynamic Re-Pricing Rules: Rule-based automated price adjustments according to competitor listings and buy-box status.
4. Bulk CSV Batch Uploads: Batch listing creation and inventory sync via CSV/Excel parsing tool actions.

---

Development & Testing

git clone https://github.com/ron2111/flipkart-seller-mcp.git
cd flipkart-seller-mcp
python -m venv .venv
source .venv/bin/activate  # Or .venv\Scripts\activate on Windows

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run full pytest suite
pytest

---

License

MIT License. See LICENSE for details.