How to Troubleshoot MCP Server Not Found Errors in qiaomu-anything-to-notebooklm

The "MCP server not found" error indicates that FastMCP cannot connect to the Playwright-based browser simulation service, which requires the server.py entry points to be running and properly configured in ~/.claude/config.json.

The qiaomu-anything-to-notebooklm skill uses Micro-Chrome Playwright (MCP) servers to bypass anti-scraping measures when fetching content from WeChat and Feishu platforms. When the skill reports that it cannot find the MCP server, the issue typically stems from missing files, incomplete dependencies, or configuration gaps that prevent FastMCP from establishing its RPC connection. Understanding how to troubleshoot MCP server not found errors requires checking several integration points between the Claude Code environment and the standalone Python processes defined in wexin-read-mcp/src/server.py and feishu-read-mcp/src/server.py.

What Triggers the MCP Server Not Found Error

The MCP architecture separates browser automation into isolated processes that register tools via FastMCP. According to the source code in joeseesun/qiaomu-anything-to-notebooklm, the server initializes with mcp = FastMCP("feishu-reader") (or similar identifiers) and exposes decorators like @mcp.tool(). The "not found" message essentially means FastMCP could not connect to the registered MCP instance, either because the process is not running, the library is missing, or the configuration path is incorrect.

Step-by-Step Troubleshooting Guide

Follow these diagnostic steps in order to systematically eliminate common failure points.

Verify MCP Server Files Exist

The server entry points must be present in your skill directory. Check that wexin-read-mcp/src/server.py (for WeChat) or feishu-read-mcp/src/server.py (for Feishu) exists.

ls ~/.claude/skills/qiaomu-anything-to-notebooklm/*/src/server.py

If these files are missing, re-clone the repository or restore the *-read-mcp folders. Ensure the src directories are in your PYTHONPATH or execute the files using absolute paths.

Install FastMCP Dependencies

The MCP server imports FastMCP from the fastmcp package. If this library is not installed, the server cannot start.

Run the provided install script to automatically resolve Python dependencies:

cd ~/.claude/skills/qiaomu-anything-to-notebooklm
./install.sh

Alternatively, install manually:

pip install fastmcp

Verify the installation:

python -c "import fastmcp; print(fastmcp.__version__)"

Configure Playwright Chromium Runtime

The MCP server launches a Chromium instance via Playwright. Without the browser binaries, the process will fail silently or crash immediately.

Install the required browser runtime:

playwright install chromium

This downloads the necessary binaries that the server.py files invoke when initializing browser contexts.

Check Claude Configuration File

MCP requires a configuration entry in ~/.claude/config.json. The diagnostic script check_env.py validates this in its "检查 MCP 配置" (Check MCP Configuration) section.

Ensure your config includes the MCP paths:

{
  "mcp": {
    "weixin": "...",
    "feishu": "..."
  }
}

Run the environment checker to confirm settings:

./check_env.py

Look specifically for lines "[7/9] MCP 服务器文件" and "[8/9] MCP 配置" to verify file presence and JSON configuration.

Start the MCP Server Process

The skill expects the MCP server to be listening on a Unix socket or TCP port as a background process. Start it manually before invoking Claude Code tools:

# For Feishu content

python ~/.claude/skills/qiaomu-anything-to-notebooklm/feishu-read-mcp/src/server.py &

# For WeChat content

python ~/.claude/skills/qiaomu-anything-to-notebooklm/wexin-read-mcp/src/server.py &

Confirm the process stays alive without tracebacks. If it exits immediately, check the preceding steps for missing dependencies.

Resolve Permission and Environment Issues

OS-level sandboxing or missing environment variables can block the MCP server. Ensure the process runs inside the same user session as Claude Code with proper write permissions.

Check that /tmp (or your specified temp directory) is writable, and verify that HOME and XDG_RUNTIME_DIR environment variables are set. If running in a restricted environment, adjust sandboxing policies to allow Chromium execution.

Quick Recovery Workflow

Execute this sequence to recover from any MCP "not found" state:

# 1. Navigate to skill directory

cd ~/.claude/skills/qiaomu-anything-to-notebooklm

# 2. Verify source files exist

ls wexin-read-mcp/src/server.py feishu-read-mcp/src/server.py

# 3. Install dependencies and browser

./install.sh

# 4. Validate environment

./check_env.py

# 5. Start required MCP server (choose one)

python feishu-read-mcp/src/server.py &

# OR

python wexin-read-mcp/src/server.py &

Once the server runs without errors, Claude Code will automatically discover it on the next invocation.

Programmatically Ensuring MCP Availability

For automation scenarios, use this Python guard to start the MCP server if it is not responding:

import subprocess
import time
import os

def ensure_feishu_mcp():
    try:
        from fastmcp import FastMCP
        FastMCP("feishu-reader").ping()
    except Exception:
        server_path = os.path.expanduser(
            "~/.claude/skills/qiaomu-anything-to-notebooklm/feishu-read-mcp/src/server.py"
        )
        subprocess.Popen(["python", server_path])
        time.sleep(2)

ensure_feishu_mcp()

# Safe to call tools now: await read_feishu_doc("https://xxx.feishu.cn/docs/...")

This pattern attempts to ping the FastMCP endpoint and falls back to spawning the process defined in feishu-read-mcp/src/server.py if the connection fails.

Summary

• Source files for the MCP server reside in wexin-read-mcp/src/server.py and feishu-read-mcp/src/server.py within the qiaomu-anything-to-notebooklm repository.
• FastMCP must be installed (pip install fastmcp) and Chromium binaries must be present (playwright install chromium).
• Configuration requires valid entries in ~/.claude/config.json, verifiable via check_env.py.
• Process management requires manually starting the Python server as a background process that persists across Claude Code invocations.
• Environment variables like HOME and writeable temp directories are essential for Playwright browser initialization.

Frequently Asked Questions

Why does the MCP server need to run separately from the main skill?

The MCP server operates as an independent process that uses Playwright to simulate browser sessions for bypassing anti-scraping measures. According to the joeseesun/qiaomu-anything-to-notebooklm architecture, it registers tools via FastMCP's RPC mechanism (mcp = FastMCP("feishu-reader")), making it a standalone service that the main main.py CLI communicates with over sockets rather than importing directly.

Can I run both WeChat and Feishu MCP servers simultaneously?

Yes. The two servers operate independently using different FastMCP instance names and can run concurrently. Start both wexin-read-mcp/src/server.py and feishu-read-mcp/src/server.py in the background, ensuring each uses distinct communication endpoints to avoid port conflicts.

What does the check_env.py script actually validate?

The check_env.py diagnostic tool performs nine environment checks, specifically "[7/9] MCP 服务器文件" (MCP server files) and "[8/9] MCP 配置" (MCP configuration). It verifies that server.py exists in the expected locations and that your ~/.claude/config.json contains properly formatted MCP entries required by the skill.

How do I know if FastMCP is properly connecting to the server?

If FastMCP connects successfully, the server process will remain active without throwing connection errors, and Claude Code will recognize the registered tools (@mcp.tool() decorated functions). You can test connectivity by attempting to fetch a protected URL after starting the server; successful content retrieval indicates the RPC mechanism is functioning correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}