内容
- [日本語 🇯🇵](./README_JP.md)
# @growi/mcp-server
[](https://badge.fury.io/js/%40growi%2Fmcp-server)
[](https://opensource.org/licenses/MIT)
A Model Context Protocol (MCP) server that connects AI models to GROWI wiki content. Enables LLMs to search and retrieve information from your organization's knowledge base for accurate, context-aware responses. Supports connections to multiple GROWI apps.
## Key Features
- 🔍 **GROWI page search and retrieval**
- 📝 **Page management**
- 🏷️ **Tag management**
- 📋 **Comment management**
- 🔗 **Share link management**
## Supported GROWI Versions
- GROWI v7.3.x or higher recommended
- Some features are also available starting from GROWI v7.2.5 and later
- [GROWI API](https://docs.growi.org/en/api/)
## Agent Skills
This repository also provides [Agent Skills](https://skills.sh/) — reusable workflow definitions that AI coding agents can load to interact with GROWI more effectively.
### Available Skills
- **growi-mcp-setup** — Walks you through setting up the GROWI MCP server. After the skill is installed, it guides you from configuring UTCP Code-Mode through verifying the connection.
- **growi-smart-save** — Save content to GROWI with intelligent path suggestions. The agent calls the `suggest-path` tool, presents destination candidates, and guides the user through page naming and visibility settings.
## Quick Start (Recommended)
The fastest way to start using GROWI. Once you install the skill, the rest of the setup (connecting the MCP server, configuring UTCP Code-Mode, verifying connectivity) is guided by the AI agent.
### 1. Install the Skill
Install the skill for your agent.
#### Claude Desktop (Cowork)
1. Go to **Customize** > **Personal Plugins** (click the + icon)
2. Click **Browse Plugins** > select the **Personal** tab
3. Click the + icon next to **Local Upload**
4. Select **Add marketplace from GitHub**
5. Enter the repository URL and click **Sync**:
```
https://github.com/growilabs/growi-mcp-server
```
#### Claude Code
Add this repository as a plugin marketplace, then install the plugin:
```
/plugin marketplace add growilabs/growi-mcp-server
/plugin install mcp-client-skills
```
#### Gemini CLI
Install as a Gemini CLI extension (includes both MCP tools and skills):
```bash
gemini extensions install https://github.com/growilabs/growi-mcp-server
```
Update with:
```bash
gemini extensions update growi-mcp-server
```
> [!IMPORTANT]
> Extensions installed from a release earlier than v1.7.1 cannot start the MCP server: only the bundled skills work and the GROWI tools never show up. Existing installs do not switch over on their own, so run `gemini extensions update growi-mcp-server` to pick up the fix.
#### Skills.sh (Vercel)
Works with Claude Code, Gemini CLI, Cursor, Codex, GitHub Copilot, and [many other agents](https://skills.sh/):
```bash
npx skills add growilabs/growi-mcp-server
```
Update with:
```bash
npx skills update
```
#### Manual Installation
Download skills directly from the repository and place them in your agent's skills directory:
1. Copy the desired skill directory from `skills/` in this repository
2. Place it in your agent's skills directory:
- Claude Code: `.claude/skills/<skill-name>/SKILL.md`
- Gemini CLI: `.gemini/skills/<skill-name>/SKILL.md`
- Other agents: `.agents/skills/<skill-name>/SKILL.md`
### 2. Restart Your Agent
After installation, restart (or reload) your agent so the skill is recognized.
### 3. Ask the AI to Set Up
Tell your agent "set up GROWI", and the `growi-mcp-setup` skill will start and guide you from the MCP server connection settings through verifying connectivity.
> [!NOTE]
> If you want to configure the MCP server directly without the skill, see [Use the MCP Server Directly](#use-the-mcp-server-directly).
## Use the MCP Server Directly
You can also register the MCP server directly with your agent instead of using the skill. Use this for a minimal setup, or as a fallback when skill-based setup is not available.
Supports simultaneous connections to multiple GROWI apps. Each app is configured using numbered environment variables.
### Single App Configuration Example
```json
{
"mcpServers": {
"growi": {
"command": "npx",
"args": ["-y", "@growi/mcp-server"],
"env": {
"GROWI_APP_NAME_1": "main",
"GROWI_BASE_URL_1": "https://your-growi-instance.com",
"GROWI_API_TOKEN_1": "your_growi_api_token"
}
}
}
}
```
### Multiple Apps Configuration Example
```json
{
"mcpServers": {
"growi": {
"command": "npx",
"args": ["-y", "@growi/mcp-server"],
"env": {
"GROWI_DEFAULT_APP_NAME": "staging",
"GROWI_APP_NAME_1": "production",
"GROWI_BASE_URL_1": "https://wiki.example.com",
"GROWI_API_TOKEN_1": "token_for_production",
"GROWI_APP_NAME_2": "staging",
"GROWI_BASE_URL_2": "https://wiki-staging.example.com",
"GROWI_API_TOKEN_2": "token_for_staging",
"GROWI_APP_NAME_3": "development",
"GROWI_BASE_URL_3": "https://wiki-dev.example.com",
"GROWI_API_TOKEN_3": "token_for_development"
}
}
}
}
```
> [!TIP]
> For skill-based setup (recommended), see [Quick Start](#quick-start-recommended).
## Available Tools (Features)
### Page Management
- `searchPages` - Search pages by keywords
- `createPage` - Create a new page
- `updatePage` - Update an existing page (full-body replace; returns the new revision ID)
- `editPage` - Edit parts of a page with string replacements without sending the whole body (supports dry-run diff preview)
- `deletePages` - Delete pages (bulk operation supported)
- `duplicatePage` - Duplicate a page (including child pages)
- `renamePage` - Change page name and path
- `getPageOutline` - Get the heading outline of a page (heading tree with line ranges and sizes, without the body); also detects setext-style (underline) headings
- `getPageSection` - Read only a part of a page, addressed by heading text or line range
- `getPageWholeContents` - Get the full markdown body of a page
- `getPage` - **Deprecated, will be removed in 2.0.0.** Alias of `getPageWholeContents` kept for backward compatibility; use `getPageOutline`, `getPageSection`, or `getPageWholeContents` instead
- `getPageInfo` - Get detailed page information
- `getRecentPages` - Get list of recently updated pages
- `getPageListingRoot` - Get root page list
- `getPageListingChildren` - Get child pages of specified page
- `pageListingInfo` - Get summary information of page listings
- `publishPage` / `unpublishPage` - Set page publish/unpublish status
### Tag Management
- `getPageTag` - Get tags of a page
- `updateTag` - Update tags of a page
- `getTagList` - Get list of tags
- `searchTags` - Search tags
### Comments & Discussions
- `getComments` - Get comments of a page
- `addComment` - Add a comment to a page
- `removeComment` - Remove a comment from a page
### Revision Management
- `listRevisions` - Get page edit history (revision bodies are omitted; bodyLength is returned instead)
- `getRevision` - Get details of a specific revision
- `listRevisionChanges` - List the authenticated user's consecutive-edit runs across all pages (requires GROWI v7.5.6 or later)
- `getRevisionDiffs` - Get unified diffs for a batch of revision pairs (requires GROWI v7.5.6 or later)
### Share Links
- `createShareLink` - Create a share link
- `getShareLinks` - Get share links of a page
- `deleteShareLinks` - Delete share links
- `deleteShareLinkById` - Delete a specific share link
### User Information
- `getUserRecentPages` - Get recent pages of a specific user
## Vault Commands
Besides serving MCP tools, the package provides commands for working with a local clone of a GROWI
Vault (the wiki exposed as a read-only git endpoint). They exist so an agent can search the wiki as
plain files — the `growi-smart-save` skill uses them for its high-accuracy destination search.
```bash
# Clone the Vault on first run, refresh it afterwards, and print where it is
npx @growi/mcp-server vault-sync --app-name main [--dest <dir>] [--no-user]
# Print the clone directory without touching the network
npx @growi/mcp-server vault-path --app-name main
# Decode on-disk Vault file names into GROWI page paths
npx @growi/mcp-server vault-decode '旧%3A old page.md'
```
The instance is named by its app name, and its base URL and credential come from the same
configuration the MCP server uses — including `GROWI_HTTP_AUTH_*` when the instance sits behind a
reverse proxy — so no token is ever passed on the command line. Requires `git` 2.31+ (2.35+ for
`--no-user`). Exit codes: `0` the clone is usable, `1` a usage or environment problem, `2` a git
failure or an unusable clone.
## Configuration Options
### Environment Variables
| Variable Name | Required | Description | Default Value |
|---------------|----------|-------------|---------------|
| `GROWI_APP_NAME_{N}` | ✅ | GROWI app identifier name (N is an integer) | - |
| `GROWI_BASE_URL_{N}` | ✅ | Base URL of GROWI instance (N is an integer) | - |
| `GROWI_API_TOKEN_{N}` | ✅ | GROWI API access token (N is an integer) | - |
| `GROWI_HTTP_AUTH_USERNAME_{N}` | | Username for HTTP auth (Basic) in front of GROWI, e.g. a reverse proxy. Required together with the password. | - |
| `GROWI_HTTP_AUTH_PASSWORD_{N}` | | Password for HTTP auth (Basic) in front of GROWI. Required together with the username. | - |
| `GROWI_DEFAULT_APP_NAME` | | Default app name to use | First configured app |
### Multiple Apps Configuration Notes
- Use integer values (1, 2, 3...) for each app configuration (sequential numbering is not required)
- Combination of `GROWI_APP_NAME_N`, `GROWI_BASE_URL_N`, and `GROWI_API_TOKEN_N` is required
- App names, base URLs, and API tokens must each be unique
- If `GROWI_DEFAULT_APP_NAME` is omitted, the first configured app becomes the default
- The app specified in `GROWI_DEFAULT_APP_NAME` will be used as the default app when the LLM does not explicitly include an app name in the prompt
### HTTP Auth (Basic) for Proxied GROWI
When a GROWI instance sits behind HTTP authentication (e.g. a reverse proxy enforcing Basic auth), set both `GROWI_HTTP_AUTH_USERNAME_{N}` and `GROWI_HTTP_AUTH_PASSWORD_{N}` for that app. You only provide a username and password; the `Basic` `Authorization` header is built for you.
- Set both or neither — providing only one fails fast with a clear error.
- When configured, the proxy credentials go in the `Authorization` header and the GROWI API token (`GROWI_API_TOKEN_{N}`) is sent via the `X-GROWI-ACCESS-TOKEN` header instead. Without it, the default `Bearer` token scheme is unchanged.
- Only Basic auth is supported for now; Digest support is planned. The variable names are scheme-agnostic so they can be reused when Digest lands.
## Developer Information
### Requirements
- Node.js 18 or higher
- pnpm (recommended)
- GROWI instance (for development and testing)
### Getting Started
1. Clone the repository
```bash
git clone https://github.com/growilabs/growi-mcp-server.git
cd growi-mcp-server
```
2. Install dependencies
```bash
pnpm install
```
3. Set up environment variables
```bash
cp .env.example .env.local
# Edit .env.local to enter GROWI connection information
```
4. Start the development server
```bash
# Test with MCP CLI
pnpm dev:cli
# Develop with MCP Inspector
pnpm dev:inspect
```
### Build and Test
```bash
# Build
pnpm build
# Lint
pnpm lint
# Run tests
pnpm test
# Run tests with coverage
pnpm test:coverage
# Run in production
pnpm start
```
### MCP Server Configuration
1. Build
```bash
pnpm build
```
2. MCP Server Configuration (Single App)
```json
{
"mcpServers": {
"growi": {
"command": "node",
"args": ["/Users/username/projects/growi-mcp-server/dist/index.js"],
"env": {
"GROWI_APP_NAME_1": "main",
"GROWI_BASE_URL_1": "https://your-growi-instance.com",
"GROWI_API_TOKEN_1": "your_growi_api_token"
}
}
}
}
```
3. MCP Server Configuration (Multiple Apps)
```json
{
"mcpServers": {
"growi": {
"command": "node",
"args": ["/Users/username/projects/growi-mcp-server/dist/index.js"],
"env": {
"GROWI_DEFAULT_APP_NAME": "production",
"GROWI_APP_NAME_1": "production",
"GROWI_BASE_URL_1": "https://wiki.example.com",
"GROWI_API_TOKEN_1": "production_token",
"GROWI_APP_NAME_2": "staging",
"GROWI_BASE_URL_2": "https://wiki-staging.example.com",
"GROWI_API_TOKEN_2": "staging_token"
}
}
}
}
```
> [!NOTE]
> Set the absolute path to the built output in "args"
### Troubleshooting
### When unable to connect to GROWI
1. Check connectivity
```bash
curl -v http://app:3000/_api/v3/healthcheck
```
2. If the `app` hostname cannot be resolved, check the devcontainer network and verify it includes `growi_devcontainer_default`
- The `.devcontainer/devcontainer.json` file sets `--network` in `runArgs`, so rebuilding the container should apply this setting
- To add manually, run the following:
- Run `docker network` command on the docker host machine
```bash
docker network connect growi_devcontainer_default growi-mcp-server-dev
```
### Contributing
Contributions to the project are welcome!
#### How to Contribute
1. **Issue Reports**: Bug reports and feature requests via [GitHub Issues](https://github.com/growilabs/growi-mcp-server/issues)
2. **Pull Requests**:
- Fork and create a branch
- Implement changes
- Add tests (if applicable)
- Create a pull request
#### Development Guidelines
- **Coding Standards**: Use [Biome](https://biomejs.dev/)
- **Commit Messages**: Follow [Conventional Commits](https://www.conventionalcommits.org/)
- **Changesets**: If your pull request changes anything users can observe, run `pnpm changeset` to record the impact level and a user-facing description, and commit the generated `.changeset/*.md` with your PR. Internal-only changes don't need one.
## License
This project is released under the [MIT License](./LICENSE).
---
## Related Links
- **[GROWI Official Site](https://growi.org/)** - Open source wiki platform
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - Standard protocol for AI and tool integration
- **[GROWI SDK TypeScript](https://github.com/growilabs/growi-sdk-typescript)** - GROWI API TypeScript SDK
- **[FastMCP](https://github.com/punkpeye/fastmcp)** - MCP server development framework
---
**Notice**
This MCP server is under development. APIs may change without notice. Please test thoroughly before using in production environments.
MCP 市场
