Nusawave MCP Server

MCP tools to read local git repos and fetch public web pages — no SerpAPI or Firecrawl required.

One shared server.py runs as multiple MCP servers (one process per repo), configured via environment variables or JSON config files.

Tools

Tool	What it does
get_repo_overview	README + key root files when present
list_docs	List markdown files under docs/
read_repo_file	Read any file inside the configured repo
fetch_public_page	HTTP fetch any public URL → plain text
audit_live_site	Fetch live site sections — only when NUSAWAVE_SITE_URL is set

Quick start

git clone https://github.com/YOUR_ORG/nusawave-mcp.git
cd nusawave-mcp

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Test on stdio (Ctrl+C to stop)
NUSAWAVE_REPO_PATH=/path/to/your/repo python server.py

Or with uv:

uv sync
NUSAWAVE_REPO_PATH=/path/to/your/repo uv run server.py

Environment variables

Variable	Default	Purpose
NUSAWAVE_MCP_NAME	nusawave	FastMCP server name (set per config entry)
NUSAWAVE_REPO_PATH	.	Local clone path for this server process
NUSAWAVE_SITE_URL	(unset)	Live site base URL; required for audit_live_site

Example: Nusawave projects

The maintainers run one server entry per repo. Copy the example config and adjust paths:

cp typingmind-mcp-config.example.json typingmind-mcp-config.json
# edit paths in typingmind-mcp-config.json

Server key	Example repo	audit_live_site
nusawave-labs-website	nusawave-labs.github.io	Yes
nusawave-forecast	nusawave-forecast	No
nusawave-extract-point	extract-point	No
nusawave-io	nusawave.io	No
nusawave-brainstormingxclaude	brainstormingxclaude	No

Connect to Claude CLI

From this repo directory:

claude mcp add my-project \
  -e NUSAWAVE_MCP_NAME=my-project \
  -e NUSAWAVE_REPO_PATH=/path/to/your/repo \
  -- /path/to/venv/bin/python /path/to/nusawave-mcp/server.py

claude mcp get my-project

Then run claude and ask it to use your MCP tools, e.g. “Use my-project to get the repo overview.”

Connect to Claude Desktop (Windows + WSL)

If Claude Desktop runs on Windows but the repo lives in WSL, use a UNC path for --directory or invoke WSL explicitly. See examples/claude-desktop-config.json.

Minimal WSL example (merge into %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "nusawave-my-project": {
      "command": "wsl",
      "args": [
        "-d", "Ubuntu", "--",
        "/home/USER/apps/mcp/nusawave/.venv/bin/python",
        "/home/USER/apps/mcp/nusawave/server.py"
      ],
      "env": {
        "NUSAWAVE_MCP_NAME": "nusawave-my-project",
        "NUSAWAVE_REPO_PATH": "/home/USER/apps/your-repo"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Connect to TypingMind

1. Start the MCP connector

./start-connector.sh YOUR_AUTH_TOKEN

Use the same token shown in TypingMind → Settings → MCP. The script prints the exact URL to paste.

Critical: Connector URL must include the port:

URL	Result
http://127.0.0.1:50880	Correct
http://localhost:50880	Correct
http://localhost	Wrong — hits nginx on port 80 → 404 / "Update required"
http://0.0.0.0:50880	Wrong — browsers cannot connect to 0.0.0.0

Verify with:

./verify-connector.sh http://127.0.0.1:50880 YOUR_AUTH_TOKEN

2. TypingMind settings

1. Settings → Advanced → Model Context Protocol
2. Delete and re-setup MCP Connector (clears stale URL)
3. Choose Private MCP Connector (not TypingMind Cloud)
4. Paste connector URL and auth token from step 1
5. Wait for green check / Get Started

3. Add local MCP servers

Click Edit Servers and paste your typingmind-mcp-config.json (copy from typingmind-mcp-config.example.json first).

4. Enable plugins

Plugins → enable the servers you need → attach to your character.

"Update required… restart MCP Connector" — TypingMind got 404 on /mcp-connect. Almost always a wrong Connector URL (missing :50880).

WSL note

If TypingMind runs in Windows but this repo is in WSL, run the MCP connector inside WSL. Paths in the config must be valid on the machine where Python runs.

Example prompts

• "Get the repo overview for my forecast project"
• "Read docs/index.md and compare with the live site"
• "Summarize the repository structure"
• "Fetch https://example.github.io/ and summarize the homepage"

License

MIT — see LICENSE.