Content
# mdn-mcp
MCP server for [MDN Web Docs](https://developer.mozilla.org) — search documentation, fetch pages, and check browser compatibility right from your AI assistant.
## Features
| Tool | Description | Data Source |
|------|-------------|-------------|
| `mdn_search` | Search MDN by keyword | MDN Search API (remote) |
| `mdn_doc` | Fetch full documentation for a page | MDN JSON API (remote) |
| `mdn_compat` | Browser compatibility check | `@mdn/browser-compat-data` (offline) |
| `mdn_list` | Browse & discover BCD features by namespace | `@mdn/browser-compat-data` (offline) |
| `mdn_css` | CSS property formal definitions | `mdn-data` (offline) |
| `mdn_http` | HTTP headers, status codes, methods reference | `@mdn/browser-compat-data` (offline) |
## Setup
No installation needed — just configure your MCP client:
<details>
<summary>VS Code / Copilot</summary>
Add to `.vscode/mcp.json`:
```json
{
"servers": {
"mdn": {
"command": "npx",
"args": ["-y", "mdn-mcp"]
}
}
}
```
</details>
<details>
<summary>Cursor</summary>
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"mdn": {
"command": "npx",
"args": ["-y", "mdn-mcp"]
}
}
}
```
</details>
<details>
<summary>Windsurf</summary>
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"mdn": {
"command": "npx",
"args": ["-y", "mdn-mcp"]
}
}
}
```
</details>
<details>
<summary>Claude Desktop</summary>
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"mdn": {
"command": "npx",
"args": ["-y", "mdn-mcp"]
}
}
}
```
</details>
<details>
<summary>Claude Code</summary>
```bash
claude mcp add --transport stdio mdn -- npx -y mdn-mcp
```
Or add to `.mcp.json` (shared with team):
```json
{
"mcpServers": {
"mdn": {
"command": "npx",
"args": ["-y", "mdn-mcp"]
}
}
}
```
</details>
<details>
<summary>Zed</summary>
Add to `settings.json`:
```json
{
"context_servers": {
"mdn": {
"command": "npx",
"args": ["-y", "mdn-mcp"]
}
}
}
```
</details>
<details>
<summary>JetBrains IDEs</summary>
Open **Settings → Tools → AI Assistant → MCP**, click **+**, and paste:
```json
{
"mcpServers": {
"mdn": {
"command": "npx",
"args": ["-y", "mdn-mcp"]
}
}
}
```
</details>
<details>
<summary>Gemini CLI</summary>
```bash
gemini mcp add mdn -- npx -y mdn-mcp
```
Or add to `~/.gemini/settings.json`:
```json
{
"mcpServers": {
"mdn": {
"command": "npx",
"args": ["-y", "mdn-mcp"]
}
}
}
```
</details>
<details>
<summary>Other MCP clients</summary>
Any MCP client that supports **stdio** transport can use this server. The command is:
```
npx -y mdn-mcp
```
See the [full list of MCP clients](https://modelcontextprotocol.io/clients).
</details>
### Local development
```bash
git clone https://github.com/anvme/mdn-mcp.git
cd mdn-mcp
npm install
node index.js
```
## Tool Reference
### `mdn_search`
Search MDN Web Docs by keyword.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | string | yes | — | Search query |
| `limit` | number | no | 5 | Max results (1–20) |
**Example:** `{ "query": "Array.map", "limit": 3 }`
### `mdn_doc`
Fetch full documentation for a specific MDN page. Supports pagination for large pages.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `path` | string | yes | — | MDN doc path or full URL |
| `sections` | string[] | no | — | Filter sections: `syntax`, `description`, `parameters`, `return_value`, `examples`, `see_also` |
| `max_length` | number | no | 5000 | Max characters to return (500–50000) |
| `start_index` | number | no | 0 | Character offset for pagination |
**Example:** `{ "path": "Web/CSS/grid", "sections": ["syntax", "description"] }`
### `mdn_compat`
Check browser compatibility for a web feature. Works offline.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `feature` | string | yes | BCD feature path, e.g. `css.properties.grid`, `api.fetch`, `javascript.builtins.Array.map` |
**Example:** `{ "feature": "javascript.builtins.Array.map" }`
Returns a Markdown table with version support for Chrome, Edge, Firefox, Safari, Opera, iOS Safari, Chrome Android, Firefox Android, Node.js, Deno, and Bun.
### `mdn_list`
Browse and discover BCD features by namespace. Filter by keyword or status.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `path` | string | no | `""` | BCD path to browse, e.g. `css.properties`, `api`, `javascript.builtins` |
| `query` | string | no | — | Filter features by keyword |
| `deprecated` | boolean | no | — | `true` = only deprecated, `false` = exclude deprecated |
| `experimental` | boolean | no | — | `true` = only experimental, `false` = exclude experimental |
| `limit` | number | no | 50 | Max features to return (1–200) |
**Examples:**
- `{ "path": "css.properties", "query": "grid" }` — find CSS grid-related properties
- `{ "path": "api", "deprecated": true, "limit": 20 }` — list deprecated Web APIs
- `{ "path": "" }` — show all top-level BCD namespaces
### `mdn_css`
Get CSS property formal definitions — syntax, initial value, inheritance, computed value, animation type, and more. Works offline.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | yes | CSS property, function, at-rule, selector, type, or unit name |
**Examples:**
- `{ "name": "grid" }` — full grid shorthand definition
- `{ "name": "display" }` — display property formal syntax
- `{ "name": ":hover" }` — :hover selector info
- `{ "name": "calc" }` — calc() function info
### `mdn_http`
Browse HTTP reference data — headers, status codes, methods, with browser compatibility.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `topic` | string | no | `""` | HTTP topic path, e.g. `headers`, `headers.Content-Type`, `status.200` |
**Examples:**
- `{ "topic": "" }` — list all HTTP categories
- `{ "topic": "headers" }` — list all HTTP headers
- `{ "topic": "headers.Content-Type" }` — browser compat for Content-Type
- `{ "topic": "status" }` — list all HTTP status codes
## Prerequisites
- Node.js >= 18
## License
MIT
