# weflow-mcp

TypeScript MCP server for calling the local [WeFlow](https://github.com/hicccc77/WeFlow) HTTP API.

WeFlow must be running locally with **API 服务** enabled. The default API base URL is `http://127.0.0.1:5031`. Except for health checks, WeFlow `/api/v1/*` endpoints require an access token.

## Install

Use directly with `npx`:

```bash
npx -y weflow-mcp
```

Or install from source:

```bash
npm install
npm run build
```

## Configuration

Set these environment variables in your MCP client:

| Variable | Default | Description |
| --- | --- | --- |
| `WEFLOW_BASE_URL` | `http://127.0.0.1:5031` | WeFlow HTTP API base URL |
| `WEFLOW_ACCESS_TOKEN` | empty | WeFlow API token |
| `WEFLOW_API_TOKEN` | empty | Fallback token name, used if `WEFLOW_ACCESS_TOKEN` is empty |
| `WEFLOW_TIMEOUT_MS` | `30000` | Request timeout in milliseconds |

## MCP client example

```json
{
  "mcpServers": {
    "weflow": {
      "command": "node",
      "args": ["/home/projects/wechat-tool/weflow-mcp/dist/index.js"],
      "env": {
        "WEFLOW_BASE_URL": "http://127.0.0.1:5031",
        "WEFLOW_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

After npm publish, you can use `npx` instead:

```json
{
  "mcpServers": {
    "weflow": {
      "command": "npx",
      "args": ["-y", "weflow-mcp"],
      "env": {
        "WEFLOW_BASE_URL": "http://127.0.0.1:5031",
        "WEFLOW_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

## Tools

- `weflow_health`: check WeFlow API health.
- `weflow_list_sessions`: list chat sessions.
- `weflow_get_messages`: get messages from a chat session.
- `weflow_get_session_messages_chatlab`: pull one session in ChatLab format.
- `weflow_list_contacts`: list contacts.
- `weflow_get_group_members`: list group members.
- `weflow_sns_timeline`: get Moments timeline.
- `weflow_sns_usernames`: list Moments publishers.
- `weflow_sns_export_stats`: get Moments export stats.
- `weflow_sns_export`: start a Moments export.
- `weflow_sns_block_delete`: get/install/uninstall Moments anti-delete status.
- `weflow_request`: call any supported WeFlow API endpoint with custom method/query/body.

## Notes

- WeFlow's API only listens on `127.0.0.1` by default.
- Before using data tools, connect WeFlow to the WeChat database in the WeFlow app.
- Media URLs returned by message APIs are usable after calling messages with `media=1`.