weclapp API Knowledge MCP

A standalone Model Context Protocol server for researching the weclapp REST API v2. Use it from Cursor, Claude Desktop, or any MCP-compatible client to explore entities, endpoints, relationships, and filter syntax — and optionally validate read patterns against your own tenant.

Not affiliated with weclapp. This is an independent open-source project maintained by the community.

What it does

It combines:

• Offline API knowledge from data/openapi_v2.json: entities, endpoints, fields, cross-schema relationships, filter syntax, and efficient read plans.

• Bounded live probes against one weclapp tenant: read-only GET requests that validate plans, inspect real response structure, and diagnose API errors.

This is not a CRUD wrapper. Its main job is to answer: how should I communicate with the weclapp API, where does data live, and how do I fetch cross-schema data efficiently?

Knowledge tools work without credentials. Live probe tools require a read-only weclapp API token.

Related MCP server: OpenAPI Schema Explorer

Tool groups

Knowledge tools:

• search_knowledge

• explain_entity

• explain_endpoint

• get_relationships

• plan_cross_entity_read

• explain_filter_syntax

• compare_approaches

Live probe tools (GET-only and bounded):

• execute_read_plan

• probe_entity_sample

• probe_list_query

Analysis and validation tools:

• analyze_response_structure

• compare_to_schema

• validate_read_plan

• validate_filter

• diagnose_api_error

• check_field_presence

See docs/TOOLS.md for parameter details and usage notes.

Requirements

• Python 3.11+

• uv (recommended) or pip

• Optional: Docker, for SSE transport via mcp-remote

• Optional: weclapp API credentials for live probes

Quick start

1. Clone and install

git clone https://github.com/serenmind/weclapp-api-knowledgebase-mcp.git
cd weclapp-api-knowledgebase-mcp
uv sync

2. Configure credentials (optional)

Live probe tools need a read-only weclapp token:

cp .env.example .env
# Edit .env and set WECLAPP_BASE_URL and WECLAPP_API_KEY

3. Run tests (optional)

uv run pytest

4. Connect your MCP client

Recommended — stdio with Cursor

Add to your Cursor MCP settings (.cursor/mcp.json or Cursor Settings → MCP):

{
  "mcpServers": {
    "weclapp-api-knowledge": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/weclapp-api-knowledgebase-mcp",
        "run",
        "weclapp-api-knowledge-mcp"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Add WECLAPP_BASE_URL and WECLAPP_API_KEY to env if you want live probes.

Alternative — Docker + SSE

cp .env.example .env
docker compose up --build

Then connect via mcp-remote:

{
  "mcpServers": {
    "weclapp-api-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8080/sse",
        "--transport",
        "sse-first"
      ]
    }
  }
}

More client examples: docs/CLIENT_SETUP.md.

Environment variables

Safety model

• No write tools are exposed.

• Live probes only issue GET requests.

• List probes cap pageSize with WECLAPP_MAX_PAGE_SIZE (default: 10).

• Credentials are read from environment only.

• The bundled OpenAPI file can be refreshed when weclapp updates v2.

Refreshing the OpenAPI spec

Replace data/openapi_v2.json with an updated weclapp v2 OpenAPI export, then restart the server. To export pre-built index JSON for inspection:

uv run weclapp-build-indexes

This writes optional artifacts to knowledge/; the MCP server reads the OpenAPI file directly at runtime.

Development

uv sync
uv run pytest
uv run ruff check src tests
MCP_TRANSPORT=stdio uv run weclapp-api-knowledge-mcp

License

MIT — see LICENSE.