Skip to main content
Glama
flipkart-seller-mcp

flipkart-seller-mcp

by ron2111

Flipkart Seller MCP Server

License: MIT Python 3.10+ Model Context Protocol

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


Related MCP server: SellerChamp 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

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.

Available Tools

5 tools
flipkart_manage_adsB

Manage Flipkart advertising campaigns (PLA / PCA / Smart ROI), budgets, and bidding.

Actions:

  • 'list_campaigns': View active or paused ad campaigns.

  • 'get_metrics': Fetch campaign performance (impressions, clicks, spend, orders, ROAS).

  • 'update_budget': Update daily budget (INR).

  • 'update_bid': Modify keyword or product bid prices.

Output format: Returns token-optimized Markdown table ('summary') or JSON ('full').

Inputs: action (required), bid_amount, campaign_id, daily_budget, +2 more. Returns: result

flipkart_manage_financialsA

Manage Flipkart seller bank settlements, payouts, and financial/tax report generation.

Actions:

  • 'get_settlements': View payout summaries, bank settlement status, UTR numbers.

  • 'request_report': Trigger generation of sales, tax, inventory, or returns reports.

  • 'download_report': Check status and retrieve download link for generated report.

Output format: Returns token-optimized Markdown table ('summary') or JSON ('full').

Inputs: action (required), date_to, date_from, report_id, +2 more. Returns: result

flipkart_manage_inventoryB

Manage Flipkart product listings, inventory levels, pricing, and catalog CRUD.

Actions:

  • 'search': Search catalog listings by SKU or FSN.

  • 'get_details': Fetch full listing specifications and current pricing/stock.

  • 'update_stock': Modify available inventory counts across warehouses.

  • 'update_price': Update MRP and Selling Price (INR).

  • 'create_listing': Create a new catalog listing (Title, SKU, Selling Price, Brand).

  • 'update_listing': Update listing title, brand, or custom attributes.

  • 'delete_listing': Deactivate or archive a listing by SKU.

Output format: Returns token-optimized Markdown table ('summary') or JSON ('full').

Inputs: action (required), fsn, mrp, sku, +7 more. Returns: result

flipkart_manage_returnsB

Manage Flipkart customer returns, RTO tracking, and Seller Protection Fund (SPF) claims.

Actions:

  • 'list_returns': List customer returns, RTOs, or replacements.

  • 'track_rto': Track return shipment delivery status and courier location.

  • 'approve_return': Approve customer return request.

  • 'spf_claim': File SPF claim for damaged, wrong, or missing return items.

Output format: Returns token-optimized Markdown table ('summary') or JSON ('full').

Inputs: action (required), return_id, return_type, tracking_id, +3 more. Returns: result

flipkart_manage_shipmentsA

Manage Flipkart seller orders & shipments.

Actions:

  • 'search': List pending, packed, RTD, or dispatched orders (filter by state/order_id).

  • 'inspect': Retrieve detailed order items, SLA deadlines, customer pincode.

  • 'mark_rtd': Transition orders to Ready to Dispatch state.

  • 'get_label': Fetch printable shipping label & tax invoice PDF URLs.

  • 'cancel': Cancel order shipment with specified reason.

Output format: Returns token-optimized Markdown table ('summary') or JSON ('full').

Inputs: action (required), state, order_id, detail_level, +2 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool covers a distinct seller domain: shipments, returns, inventory, ads, and financials. There is no overlap in purpose, and the actions within each tool further differentiate the operations.

    Naming Consistency5/5

    All tools follow a consistent 'flipkart_manage_X' pattern (e.g., flipkart_manage_shipments, flipkart_manage_returns). This makes it easy to predict the tool's domain from its name.

    Tool Count5/5

    5 tools is well-scoped for a seller platform. It covers all major functionalities without being too few or too many, allowing for focused and manageable interactions.

    Completeness5/5

    The tool set covers the full lifecycle of seller operations: order and shipment management, returns and RTO, inventory and catalog CRUD, advertising, and financials. No obvious gaps are apparent.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      A Shopify-focused MCP server that enables AI agents to manage store operations like order tracking, product discovery, and checkout link generation. It facilitates customer-facing interactions including shipping estimates and real-time inventory searches.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI agents to manage multi-marketplace e-commerce operations by connecting to the SellerChamp API. It supports inventory reporting, cross-listing analysis, order management, and bulk updates across platforms like Amazon, eBay, and Shopify.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for Ozon sellers with a built-in Chinese operations knowledge base and 466 API methods, enabling AI agents to discover, understand, and execute Ozon Seller and Performance API operations safely and efficiently.
      1
      MIT