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

Related MCP server: Clind MCP Server

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

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