Skip to content

Commit 5ea5393

Browse files
jinzcdevjinzcdev
committed
docs: Add README
1 parent 5f00d2a commit 5ea5393

File tree

1 file changed

+181
-0
lines changed

1 file changed

+181
-0
lines changed

‎README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# LeetCode MCP Server
2+
3+
![stars](https://img.shields.io/github/stars/jinzcdev/leetcode-mcp-server)
4+
![GitHub license](https://img.shields.io/github/license/jinzcdev/leetcode-mcp-server.svg)
5+
6+
The LeetCode MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that provides seamless integration with LeetCode APIs, enabling advanced automation and intelligent interaction with LeetCode's programming problems, contests, solutions, and user data.
7+
8+
## Features
9+
10+
- **Multi-site Support**: Supports both leetcode.com and leetcode.cn platforms
11+
- **Problem Data Retrieval**: Obtain detailed problem descriptions, constraints, examples, and solution approaches
12+
- **User Data Access**: Retrieve user profiles, submission history, and contest performance
13+
- **Advanced Search Capabilities**: Filter problems by tags, difficulty levels, and categories
14+
- **Daily Challenge Tracking**: Easily access daily challenge problems
15+
16+
## Prerequisites
17+
18+
1. Node.js runtime environment
19+
2. (Optional) LeetCode session cookie for authenticated API access
20+
21+
## Installation
22+
23+
```bash
24+
# Install from npm
25+
npm install mcp-server-leetcode -g
26+
27+
# Run the server with default settings (Global LeetCode site)
28+
mcp-server-leetcode
29+
30+
# Run with China site configuration
31+
mcp-server-leetcode --site cn
32+
33+
# Run with authentication (for accessing private data)
34+
mcp-server-leetcode --site global --session <YOUR_LEETCODE_SESSION_COOKIE>
35+
```
36+
37+
## Usage
38+
39+
### Visual Studio Code Integration
40+
41+
Add the following JSON configuration to your User Settings (JSON) file Code. Access this by pressing `Ctrl + Shift + P` and searching for `Preferences: Open User Settings (JSON)`.
42+
43+
```json
44+
{
45+
"mcp": {
46+
"servers": {
47+
"leetcode": {
48+
"type": "stdio",
49+
"command": "mcp-server-leetcode",
50+
"args": [
51+
"--site",
52+
"global",
53+
"--session",
54+
"<YOUR_LEETCODE_SESSION_COOKIE>"
55+
]
56+
}
57+
}
58+
}
59+
}
60+
```
61+
62+
For LeetCode China site, modify the `--site` parameter to `cn`.
63+
64+
## Environment Variables
65+
66+
The server supports the following environment variables:
67+
68+
- `LEETCODE_SITE`: LeetCode API endpoint ('global' or 'cn')
69+
- `LEETCODE_SESSION`: LeetCode session cookie for authenticated API access
70+
71+
**Priority Note**:
72+
Command-line arguments take precedence over environment variables when both are specified. For example:
73+
74+
- If `LEETCODE_SITE=cn` is set but you run `mcp-server-leetcode --site global`, the server will use `global`.
75+
- If `LEETCODE_SESSION` exists but you provide `--session "new_cookie"`, the command-line session value will be used.
76+
77+
## Tools
78+
79+
The server provides a comprehensive suite of tools categorized by functionality and platform compatibility.
80+
81+
### Problem Tools
82+
83+
Available on both Global and China sites, with optional authentication.
84+
85+
| Tool Name | Description | Parameters |
86+
|-----------|-------------|------------|
87+
| **leetcode_daily_challenge** | Retrieves today's LeetCode Daily Challenge with complete metadata | None |
88+
| **leetcode_problem** | Retrieves comprehensive details for a specified LeetCode problem | `titleSlug` (string, required): Problem URL identifier (e.g., 'two-sum') |
89+
| **leetcode_search_problems** | Executes filtered searches across LeetCode problems | `category` (string, optional): Problem classification<br>`tags` (string[], optional): Topic tags filter<br>`difficulty` (string, optional): Problem complexity level ('EASY', 'MEDIUM', 'HARD')<br>`limit` (number, optional): Maximum results count<br>`offset` (number, optional): Pagination offset |
90+
91+
### User Tools
92+
93+
Provides user-specific data across both platforms.
94+
95+
| Tool Name | Description | Parameters |
96+
|-----------|-------------|------------|
97+
| **leetcode_user_profile** | Retrieves complete profile information for a LeetCode user | `username` (string, required): LeetCode username |
98+
| **leetcode_user_contest_ranking** | Obtains contest ranking statistics for a user | `username` (string, required): LeetCode username<br>`attended` (boolean, optional): Filter for attended contests only |
99+
100+
### Global Site-Specific User Tools
101+
102+
Exclusive to leetcode.com platform.
103+
104+
| Tool Name | Description | Parameters |
105+
|-----------|-------------|------------|
106+
| **leetcode_recent_submissions** | Retrieves a user's recent submission history (Global) | `username` (string, required): LeetCode username<br>`limit` (number, optional): Results limit |
107+
| **leetcode_recent_ac_submissions** | Retrieves a user's recent accepted submissions (Global) | `username` (string, required): LeetCode username<br>`limit` (number, optional): Results limit |
108+
109+
### China Site-Specific User Tools
110+
111+
Exclusive to leetcode.cn platform.
112+
113+
| Tool Name | Description | Parameters |
114+
|-----------|-------------|------------|
115+
| **leetcode_user_recent_ac_submissions** | Retrieves recent accepted submissions (China) | `username` (string, required): LeetCode China username<br>`limit` (number, optional): Results limit |
116+
117+
### Authenticated Common Tools
118+
119+
Requires session authentication, available on both platforms.
120+
121+
| Tool Name | Description | Parameters |
122+
|-----------|-------------|------------|
123+
| **leetcode_user_status** | Retrieves authenticated user's current status | None |
124+
| **leetcode_problem_submission_detail** | Provides detailed submission analysis | `id` (number, required): Submission ID |
125+
| **leetcode_user_progress_questions** | Tracks user's problem-solving progress | `offset` (number, required): Pagination offset<br>`limit` (number, required): Results limit<br>`questionStatus` (enum, optional): 'ATTEMPTED' or 'SOLVED' filter<br>`difficulty` (string[], optional): Complexity level filter |
126+
127+
### Global Site-Specific Authenticated Tools
128+
129+
Authenticated tools exclusive to leetcode.com.
130+
131+
Name | Description | Parameters |
132+
|-----------|-------------|------------|
133+
| **leetcode_user_all_submissions** | Retrieves paginated submission history (Global) | `limit` (number, required): Results limit<br>`offset` (number, required): Pagination offset<br>`questionSlug` (string, optional): Problem identifier filter |
134+
135+
### China Site-Specific Authenticated Tools
136+
137+
Authenticated tools exclusive to leetcode.cn.
138+
139+
| Tool Name | Description | Parameters |
140+
|-----------|-------------|------------|
141+
| **leetcode_user_all_submissions** | Retrieves comprehensive submission history (China) | `limit` (number, required): Results limit<br>`offset` (number, required): Pagination offset<br>`questionSlug` (string, optional): Problem identifier<br>`lang` (string, optional): Programming language filter<br>`status` (string, optional): Submission status filter<br>`lastKey` (string, optional): Pagination token |
142+
143+
## Resources
144+
145+
The server provides reference resources for platform metadata access via URI endpoints.
146+
147+
| Resource Name | Description | URI |
148+
|---------------|-------------|-----|
149+
| **problem-categories** | Complete problem classification categories | `leetcode://problems/categories/all` |
150+
| **problem-tags** | Algorithmic and data structure tags collection | `leetcode://problems/tags/all` |
151+
| **problem-langs** | Supported programming languages list | `leetcode://problems/langs/all` |
152+
| **solution-article** | A LeetCode solution article | global: `leetcode://solutions/{topicId}`<br>cn: `leetcode://solutions/{slug}` |
153+
154+
## Authentication
155+
156+
Advanced features require LeetCode session authentication:
157+
158+
1. Log in to LeetCode ([Global](https://leetcode.com) or [China](https://leetcode.cn) site)
159+
2. Extract `LEETCODE_SESSION` cookie from browser developer tools
160+
3. Configure server with `--session` flag or `LEETCODE_SESSION` environment variable
161+
162+
## Response Format
163+
164+
All tools return JSON-formatted responses with the following structure:
165+
166+
```json
167+
{
168+
"content": [
169+
{
170+
"type": "text",
171+
"text": "JSON_DATA_STRING"
172+
}
173+
]
174+
}
175+
```
176+
177+
The `JSON_DATA_STRING` contains either the requested data or an error message for failed requests.
178+
179+
## License
180+
181+
This project is licensed under the MIT License.

0 commit comments

Comments
 (0)