Espressif Documentation MCP Server: Power Your AI Agents with Espressif Docs · Developer Portal

[giscus[bot]]

Espressif Documentation MCP Server: Power Your AI Agents with Espressif Docs · Developer Portal

This article introduces how to connect your AI agent to official, up-to-date Espressif documentation directly inside your editor — with installation steps, example prompts, and best practices.

https://developer.espressif.com/blog/2026/04/doc-mcp-server/

[dzungpv]

I want you add support for Google Antigravity too

[espwangning]

Thank you for the feedback. In case you haven't checked the udpates yet, we added how to install the MCP server for Antigravity last week. See https://developer.espressif.com/blog/2026/04/doc-mcp-server/#how-to-install-the-mcp-server

[dzungpv]

Thank you for the feedback. In case you haven't checked the udpates yet, we added how to install the MCP server for Antigravity last week. See https://developer.espressif.com/blog/2026/04/doc-mcp-server/#how-to-install-the-mcp-server

But rate limited, why not opensource it all so we can host it local for use?

[espwangning]

The rate limits (40/hour, 200/day per user) are there to ensure fair use and prevent any single user or script from overloading the service for everyone else.

[diplfranzhoepfinger]

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "espressif": {
      "type": "remote",
      "url": "https://mcp.espressif.com/docs"
    }
  }
}

then call

opencode mcp auth espressif

[espwangning]

Thank you for sharing the configuration for Opencode!

[f-hoepfinger-hr-agrartechnik]

pls add Opencode as well.

[espwangning]

pls add Opencode as well.

We have added Opencode installation steps to the main text in our latest update. Thanks for the suggestion!

[GabrielOnzi]

i could not make it work on Gemini CLI... :(

[GabrielOnzi]

Now i manage to do it, my mistake.

It is very important to follow the exact steps described, and if something wrong happen, remove the MCP and doing it again worked for me. Thanks!

[shaojun]

does not work for auth in WSL.
in WSL when ran the auth command:

opencode mcp auth espressif-docs

┌  MCP OAuth Authentication
│
◇  Could not open browser automatically
│
▲  Please open this URL in your browser to authenticate:
│
●  https://mcp.espressif.com/docs/authorize?response_type=code&client_id=xxxxx-xxxx-xxx-xx-9523c74616d5&code_challenge=nSGTA1Pgy4Td3enoBfewwerfweGwAf8OOFrCvI37inzIGZjSCci0Ig&code_challenge_method=S256&redirect_uri=http%3A%2F%2F127.0.0.1%3A19876%2Fmcp%2Foauth%2Fcallback&state=8120551f52da5361875ba4434da1ead9df0b519b8cacaf18597462480c8fac48&scope=read%3Auser&resource=https%3A%2F%2Fmcp.espressif.com%2Fdocs

after pasted that url to browser in windows host, the browser will be directed to sth like http://127.0.0.1:19876/mcp/oauth/callback?code=4L7-i_zR_B9zSwK2uLA4yvR4Ju1waVT3s&state=8120551f52da538597462480c8fac48
but failed even i've add a port remapping of 19876.

[espwangning]

Thanks for the detailed report! Here's a workaround you can try while we work on a proper fix.

Instead of using port remapping, you can replace 127.0.0.1 in the auth URL with your WSL's actual IP address, so the Windows browser knows to route the callback to WSL directly.

Steps:

1. Get your WSL IP:

ip addr show eth0 | grep "inet " | awk '{print $2}' | cut -d/ -f1

2. Take the URL that opencode prints and replace 127.0.0.1 with the IP you got above. For example, change:

redirect_uri=http%3A%2F%2F127.0.0.1%3A19876%2Fmcp%2Foauth%2Fcallback

to:

redirect_uri=http%3A%2F%2F172.24.16.45%3A19876%2Fmcp%2Foauth%2Fcallback

(replacing 172.24.16.45 with your actual WSL IP)

3. Paste the modified URL into your Windows browser and complete the login.

We tested that the Espressif auth server accepts non-localhost IPs in the redirect URI, so this should work. Could you give it a try and let us know if it resolves the issue?

[shaojun]

yes, this is my corrected url as your suggested( see the ip of 172.22.215.159 which is my WSL):

https://mcp.espressif.com/docs/authorize?response_type=code&client_id=aa2532b7-7bdb-4495-b804-9523c74616d5&code_challenge=XDsRLWHtfd00UjtVIdXMCpRUAjEGCGpnXLmF73wM2dw&code_challenge_method=S256&redirect_uri=http%3A%2F%2F172.22.215.159%3A19876%2Fmcp%2Foauth%2Fcallback&state=9a3bfd11ed8d06e12904ba038cadfd0dbace97b0db8d72f3c8f6a8c28678f1cd&scope=read%3Auser&resource=https%3A%2F%2Fmcp.espressif.com%2Fdocs

after auth with github credential in my windows host's browser, the browser said done successfully, but in wsl show error:

opencode mcp auth espressif-docs

┌  MCP OAuth Authentication
│
◇  Could not open browser automatically
│
▲  Please open this URL in your browser to authenticate:
│
●  https://mcp.espressif.com/docs/authorize?response_type=code&client_id=aa2532b7-7bdb-4495-b804-9523c74616d5&code_challenge=XDsRLWHtfd00UjtVIdXMCpRUAjEGCGpnXLmF73wM2dw&code_challenge_method=S256&redirect_uri=http%3A%2F%2F127.0.0.1%3A19876%2Fmcp%2Foauth%2Fcallback&state=9a3bfd11ed8d06e12904ba038cadfd0dbace97b0db8d72f3c8f6a8c28678f1cd&scope=read%3Auser&resource=https%3A%2F%2Fmcp.espressif.com%2Fdocs
│
■  Authentication failed
│
■  OAuth completion failed
│
└  Done

[espwangning]

I tested on WSL on Windows 10, and the following workaround works:

docs@DESKTOP-FVB9DD4:~$ netsh.exe interface portproxy add v4tov4 listenport=19876 listenaddress=127.0.0.1 connectport=19876 connectaddress=$(hostname -I | awk ' {print $1}')

docs@DESKTOP-FVB9DD4:~$ opencode mcp auth espressif-docs

┌  MCP OAuth Authentication
│
◇  Authentication successful!
│
└  Done

If this does not work for you, I suggest you check with OpenCode, since this issue cannot be resolved from the MCP server side. Thanks!

[shaojun]

ask the code agent (opencode, codex and etc.) to do build, flash and monitor, is this a suggested way to do the development?
i understand the build and flash is straigthforward, but how about the monitoring? i suspect the calling to idf.py monitor is a blocking CLI call?

[espwangning]

This is not covered by the doc MCP server, but what the ESP-IDF Tools Local MCP Server designed for. I suggest you check step 3 in the ESP-IDF Tools Local MCP Server blog https://developer.espressif.com/blog/2026/04/esp-idf-tools-mcp-server/#example-workflow

If you still have questions, you can post comments below that blog.

[cofiemark]

Now that we have MCP Server for Espressif Docs, the next most desirable thing developers look forward to is Official Espressif Agent Skills for the various development surfaces for Claude Code, Antigravity, Codex, etc.
Can you imagine a world where Agent Skills for ESP-NOW, WiFi, FreeRTOS, A2DP, Bluetooth-LE, Power Management best practices, etc. are all specific Skills for Ai Agents to adopt, paired with this Espressif Docs MCP server for project development?
Agent Skills from Espressif would be an amazing resource for developers indeed. We can't wait for such a great resource.

[espwangning]

Thank you for your suggestion! I'll pass this to corresponding team for evaluation.

[RuriLothlorien]

I reproduced a Codex-specific authentication failure with this Documentation MCP server on native Windows.

codex mcp login espressif-documentation completes successfully in the browser and CLI. However, a fresh Codex process then receives HTTP 403 with this JSON body during the MCP initialize request, before any tools are exposed:

{"error":{"code":"403","message":"Forbidden","id":"hnd1::q4pmn-1787899236531-b4965e4cbded"}}

The Component Registry and Espressif Engineering MCP endpoints work in equivalent smoke tests. Repeating logout/login and starting a fresh process does not change the result.

I filed a detailed Codex issue with the configuration, reproduction steps, and related OAuth issues:

openai/codex#41291

This differs from the WSL callback-routing report above: the OAuth callback succeeds here, and the 403 occurs afterward during MCP initialization. If the Espressif team can confirm whether this 403 includes a WWW-Authenticate insufficient_scope challenge, that would help determine whether Codex OAuth step-up handling is involved.