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

> Fix MCP server not found errors in qiaomu-anything-to-notebooklm by ensuring server.py runs and config is set up correctly. Resolve Playwright connection issues quickly.

- Repository: [向阳乔木/qiaomu-anything-to-notebooklm](https://github.com/joeseesun/qiaomu-anything-to-notebooklm)
- Tags: how-to-guide
- Published: 2026-05-16

---

**The "MCP server not found" error indicates that FastMCP cannot connect to the Playwright-based browser simulation service, which requires the [`server.py`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/wexin-read-mcp/src/server.py) and [`feishu-read-mcp/src/server.py`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/wexin-read-mcp/src/server.py) (for WeChat) or [`feishu-read-mcp/src/server.py`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/feishu-read-mcp/src/server.py) (for Feishu) exists.

```bash
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:

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

```

Alternatively, install manually:

```bash
pip install fastmcp

```

Verify the installation:

```bash
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:

```bash
playwright install chromium

```

This downloads the necessary binaries that the [`server.py`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/check_env.py) validates this in its *"检查 MCP 配置"* (Check MCP Configuration) section.

Ensure your config includes the MCP paths:

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

```

Run the environment checker to confirm settings:

```bash
./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:

```bash

# 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:

```bash

# 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:

```python
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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/wexin-read-mcp/src/server.py) and [`feishu-read-mcp/src/server.py`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/wexin-read-mcp/src/server.py) and [`feishu-read-mcp/src/server.py`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/check_env.py) script actually validate?

The [`check_env.py`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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.