interactive-leetcode-mcp

Interactive LeetCode MCP

MCP server for LeetCode practice with learning-guided hints, solution submission, and AI-driven authentication.

Prerequisite: Ensure MCP Server Is Connected

Before anything else, check whether the get_started tool is available. If it is, the server is connected — skip to the next section.

If get_started is NOT available, the MCP server needs to be installed. Ask the user for confirmation before proceeding — explain that this will download and run an npm package.

The npm package is @sperekrestova/interactive-leetcode-mcp (source: GitHub). It runs over stdio transport. Requires Node.js >= 20.

After the user confirms, add to the client's MCP configuration (the exact file varies by client):

{
  "mcpServers": {
    "leetcode": {
      "command": "npx",
      "args": ["-y", "@sperekrestova/[email protected]"]
    }
  }
}

For Claude Code specifically, you can also run:

claude mcp add --transport stdio leetcode -- npx -y @sperekrestova/[email protected]

Pin a specific version (shown above) rather than using @latest to avoid executing untested code. Users can check for newer versions at the npm page or GitHub releases and update the pinned version after reviewing the changelog.

After adding the server, tell the user to restart their session so the MCP tools become available. Do not proceed with the session flow until get_started is accessible.

First Action: Always Call get_started

At the START of every LeetCode session, call the get_started tool. It returns the full usage guide: prompt invocation rules, session flow, learning mode rules, auth flow, and language map.

Do not skip this — it is a single fast call, not redundant with tool descriptions. The server has MCP prompts that must be explicitly invoked — they are NOT auto-active. The get_started response tells you exactly when and how.

Session Flow (Critical)

1. Call get_started              <-- FIRST, every session
2. Invoke leetcode_learning_mode <-- BEFORE any problem discussion
3. User picks a problem
4. Invoke leetcode_problem_workflow(problemSlug, difficulty)
5. Invoke leetcode_workspace_setup(language, problemSlug, codeTemplate)
6. Guide user with progressive hints (4 levels)
7. submit_solution when ready

Steps 2, 4, and 5 are MCP prompt invocations. Invoke them via the Skill tool or equivalent prompt mechanism. All three must happen BEFORE the user starts coding.

Step 2 is non-negotiable. If you skip leetcode_learning_mode, you will bypass the progressive hint system and may show solutions prematurely. Invoke it before searching for or discussing any problem.

Prompt Invocation Rules

Prompt	When	Params
leetcode_learning_mode	START of session, before any problem	none
leetcode_problem_workflow	After user selects a problem	problemSlug, difficulty
leetcode_workspace_setup	Before user starts coding	language, problemSlug, codeTemplate
leetcode_authentication_guide	On auth need, 401 errors, expired creds	none

Learning Mode Rules

• Never show a full solution without working through hint levels 1 → 2 → 3
• Level 1: Guiding questions ("What pattern do you see?")
• Level 2: General approaches ("Consider using a hash map...")
• Level 3: Specific hints ("Iterate once, tracking seen values...")
• Level 4: Pseudocode or partial implementation
• Only show complete solutions when explicitly requested AFTER earlier hints
• get_problem_solution returns full community solutions — Level 4 or explicit request only

Tool Quick Reference

Tool	Purpose	Auth?
get_daily_challenge	Today's challenge	No
get_problem	Problem by slug	No
search_problems	Find by tags/difficulty/keywords	No
list_problem_solutions	Solution metadata (topicIds)	No
get_problem_solution	Full solution — Level 4 only	No
submit_solution	Submit code	No*
get_user_profile	Any user's stats	No
get_recent_submissions	Recent submissions	No
get_recent_ac_submissions	Accepted submissions	No
get_user_contest_ranking	Contest ranking	No
start_leetcode_auth	Start auth flow	No
save_leetcode_credentials	Validate + save creds	No
check_auth_status	Check credential state	No
get_user_status	Current user info	Yes
get_problem_submission_report	Submission detail	Yes
get_problem_progress	Progress with filters	Yes
get_all_submissions	All submissions	Yes

*submit_solution requires saved credentials to succeed.

Auth Flow

1. Before auth-sensitive actions → call check_auth_status
2. If not authenticated or expired → ask the user if they want to authenticate. Explain that this will store LeetCode session cookies locally at ~/.leetcode-mcp/credentials.json (owner-read/write only). Do not proceed without consent.
3. After consent → invoke leetcode_authentication_guide prompt
4. Call start_leetcode_auth → the prompt will guide the user through providing credentials → call save_leetcode_credentials with the values the user provides
5. On success → retry original action
6. On 401 from any tool → repeat from step 1

Always delegate auth guidance to the leetcode_authentication_guide prompt. Do not improvise your own auth instructions — the prompt handles browser-specific guidance, error recovery, and troubleshooting.

Credential storage: The MCP server stores credentials locally at ~/.leetcode-mcp/credentials.json with file permissions 0o600 (owner-read/write only). Only csrftoken, LEETCODE_SESSION, and a createdAt timestamp are stored. Credentials are never transmitted to any third party — they are used exclusively for direct LeetCode API calls. Typical credential lifetime is 7-14 days.

Submission Language Map

User says	Pass to submit_solution
Python / Python 3	python3
Python 2	python
Java	java
C++	cpp
JavaScript	javascript
TypeScript	typescript

Default: "Python" without version → python3.

Resources (Read-Only Lookups)

Resource URI	What it provides
categories://problems/all	All problem categories
tags://problems/all	All 60+ topic tags
langs://problems/all	All supported submission languages
problem://{titleSlug}	Problem detail
solution://{topicId}	Solution detail (same learning-mode rules apply)

Common Mistakes

• Jumping to problem search before invoking leetcode_learning_mode
• Showing full solutions without progressing through hint levels 1 → 2 → 3
• Not invoking leetcode_workspace_setup — code should live in a file, not only in chat
• Guiding auth manually instead of invoking leetcode_authentication_guide
• Passing "Python" to submit_solution instead of "python3"
• Not calling check_auth_status before auth-sensitive operations
• Skipping get_started and assuming tool descriptions are sufficient