How to Fix “mcp.server.fastmcp” Could Not Be Resolved in Python
Fix the mcp.server.fastmcp error by matching your MCP Python SDK version, imports, and active interpreter.
mcp.server.fastmcp was removed in MCP Python SDK v2. If your project uses v2, replace the old v1 import with:
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("Demo")The same error can also come from installing the package into a different Python environment. Check the SDK version and interpreter before changing code. The official migration guide documents the breaking module move and class rename: MCP Python SDK migration guide.
1. Identify which problem you have
There are two common causes, and the title alone does not prove which one applies:
- SDK v2 with v1 code: the
mcp.server.fastmcpmodule no longer exists. Usemcp.server.mcpserverandMCPServer. - Wrong or missing environment: the package is absent from the interpreter running your script, IDE task, test runner, or service.
Run these commands in the exact environment that launches your program:
python -c "import sys; print(sys.executable)"
python -m pip show mcp
python -c "import mcp; print(getattr(mcp, '__version__', 'version not exposed'))"If pip show reports nothing, install the SDK in that environment. The official project documents both supported installation forms:
uv add "mcp[cli]"
# or
python -m pip install "mcp[cli]"Installation does not rewrite old imports; you still need the v2 migration when v2 is installed. See the official SDK installation and quickstart.
2. Repair a project that uses SDK v2
Change every import beneath mcp.server.fastmcp, not only the class name:
# Old v1 code
from mcp.server.fastmcp import FastMCP
# v2 code
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("Demo")Search the whole repository for stale paths:
rg "mcp\.server\.fastmcp|FastMCP" .Update imports in application code, tests, examples, entry points, and plugins. The migration guide says submodules that were under mcp.server.fastmcp.* are also under mcp.server.mcpserver.* in v2. After editing, run the import check with the same command used by deployment:
python -c "from mcp.server.mcpserver import MCPServer; print(MCPServer)"3. Keep existing v1 code temporarily
If a tutorial or application must remain unchanged, install a compatible SDK v1 dependency in the same environment and pin the major version in your project configuration. Do not install the current v2 line and expect the v1 path to remain available.
This option reduces immediate code changes but keeps the project on the older major line. Migrating to v2 follows the current stable-line guidance and may require additional changes elsewhere. Choose based on your application’s compatibility requirements; the supplied sources do not define one universal v1 pin for every project.
4. Verify the interpreter used by your editor or runner
A terminal can use one virtual environment while an IDE, task runner, Docker image, or systemd service uses another. Compare the executable and package location from the failing process:
python -c "import sys; print(sys.executable)"
python -m pip --version
python -c "import mcp, inspect; print(inspect.getfile(mcp))"In an IDE, select the interpreter whose path matches sys.executable. In CI, install with python -m pip (or the equivalent project tool) rather than an unqualified pip. In Docker, run the checks inside the image that starts the service.
5. A repeatable migration checklist
- Record the Python executable and resolved
mcpversion. - Search for
mcp.server.fastmcpandFastMCP. - If the project is on v2, replace them with
mcp.server.mcpserverandMCPServer. - Review every nested import under the moved module.
- Regenerate lock files or update dependency constraints deliberately.
- Run the import check, unit tests, and the real server entry point in the same environment.
- Commit the dependency and import changes together so another machine resolves the same major version.
6. Troubleshooting common errors
| Error or symptom | Likely cause | Fix |
|---|---|---|
ModuleNotFoundError: No module named 'mcp.server.fastmcp' |
SDK v2 with v1 import | Use from mcp.server.mcpserver import MCPServer, or deliberately install a compatible v1 dependency. |
ModuleNotFoundError: No module named 'mcp' |
Package is not installed in the active interpreter | Run uv add "mcp[cli]" or python -m pip install "mcp[cli]" in that environment. |
| Import works in a terminal but fails in VS Code or another IDE | IDE selected a different interpreter | Compare the IDE interpreter path with sys.executable and switch environments. |
| Import works locally but fails in CI or a container | Dependency was not installed or lock files differ | Install from the committed dependency configuration and print the version during the build. |
Changing only FastMCP still leaves an import error |
A nested mcp.server.fastmcp.* import remains |
Search the repository and move every affected import to the v2 module tree. |
A copied quickstart uses FastMCP while your install is v2 |
Documentation example targets the older API shape | Reconcile the example with the migration guide and your locked SDK major version. |
7. Dependency, reliability and maintenance notes
Pin the major version
Use a lock file or an explicit major-version constraint so a fresh environment does not silently switch import APIs. Review upgrades as code changes, because a major SDK migration can involve module and class renames.
Keep diagnostics reproducible
Capture sys.executable, python -m pip show mcp, and the full traceback in bug reports. These three details distinguish an API migration from an environment mismatch quickly.
Separate import checks from server checks
First verify that the module imports. Then start the server and exercise a tool or client connection. This isolates packaging failures from protocol or application failures.
8. Or skip the browser setup
If your MCP server needs website images for an agent workflow, ScreenshotNeo provides a screenshot API and MCP server. Its capture request removes cookie banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Responses identify the page verdict and billing status, and an MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI clients.
Use the ScreenshotNeo API documentation for the complete option list. A one-call capture looks like this:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.
9. FAQ
Is this error caused by Python itself?
Usually it reflects the installed MCP SDK’s module layout or the interpreter environment, rather than a Python language problem.
Can I keep using tutorials that say FastMCP?
Yes, if you intentionally use a compatible v1 SDK. Otherwise, translate the imports and class construction to the v2 API.
Should I uninstall the old package before installing v2?
Use your project’s dependency manager and lock file to make the desired version explicit. The important check is which version the executing interpreter resolves.
Why does the official repository still show a FastMCP-shaped example?
The repository’s quickstart material can present older-shaped code while the migration guide and release notes describe v2 changes. Always reconcile examples with your installed major version.
