Skip to main content

Kiro MCP Integration with BookStack

Kiro MCP Integration with BookStack

Overview

This page documents how to connect your BookStack instance to Kiro — Amazon's agentic AI IDE — as an MCP server. Once configured, Kiro's AI agent can search your documentation, read page content for context, create new pages, and update existing ones without leaving your development environment.

The integration uses the bookstack-mcp npm package as a local MCP server. Kiro connects to it via .kiro/settings/mcp.json and treats BookStack as a tool it can invoke during any agentic coding session.

What You Can Do

With BookStack wired into Kiro, you can say things like:

  • Search docs during coding — "Find our internal API spec in BookStack before implementing this client."
  • Read pages for context — "Read the BookStack page on our DB2 schema before writing this migration."
  • Generate documentation automatically — "After finishing this module, create a BookStack page summarizing how it works."
  • Update existing pages — "Update the Linux hardening page with the new sysctl values we just tested."
  • Keep docs in sync via Agent Hooks — Configure Kiro to auto-update a BookStack page whenever a key file changes.

Prerequisites

  • Kiro IDE installed (macOS, Windows, or Linux) — kiro.dev
  • An AWS account (required for Kiro authentication)
  • Node.js 18 or newer (for running the MCP server via npx)
  • A running BookStack instance with API access enabled
  • A BookStack API Token ID and Token Secret (see below)

Setup

Step 1 — Generate a BookStack API Token

  1. Log into BookStack as an admin (or as the user you want Kiro to act as)
  2. Click your profile avatar in the top-right → Edit Profile
  3. Scroll down to the API Tokens section and click Create Token
  4. Give it a name (e.g., Kiro MCP) and optionally set an expiry date
  5. Click Save — copy the Token ID and Token Secret immediately. The secret is only shown once.
The token inherits the permissions of the BookStack user it belongs to. Create a dedicated user with only the access Kiro needs — or use a read-only token if you don't want Kiro writing content.

Step 2 — Create the Kiro MCP Config File

Kiro reads MCP server definitions from a JSON file at one of two locations:

  • Workspace-level: .kiro/settings/mcp.json inside your project root — applies only to that project
  • User-level: ~/.kiro/settings/mcp.json in your home directory — applies to all projects

Create or edit the appropriate file and add the following block:

{
  "mcpServers": {
    "bookstack": {
      "command": "npx",
      "args": ["-y", "bookstack-mcp"],
      "env": {
        "BOOKSTACK_BASE_URL": "${BOOKSTACK_BASE_URL}",
        "BOOKSTACK_TOKEN_ID": "${BOOKSTACK_TOKEN_ID}",
        "BOOKSTACK_TOKEN_SECRET": "${BOOKSTACK_TOKEN_SECRET}",
        "BOOKSTACK_ENABLE_WRITE": "true"
      }
    }
  }
}

The ${VAR_NAME} syntax tells Kiro to read the value from your shell environment at startup. Export the three variables in your shell profile (e.g., ~/.zshrc or ~/.bashrc):

export BOOKSTACK_BASE_URL="https://bookstack.x1a.net"
export BOOKSTACK_TOKEN_ID="your-token-id-here"
export BOOKSTACK_TOKEN_SECRET="your-token-secret-here"
Write operations are disabled by default. The bookstack-mcp server ships in read-only mode. You must explicitly set BOOKSTACK_ENABLE_WRITE=true in the env block to allow Kiro to create or update pages. Omit it if you only want read access.

Step 3 — Reload Kiro

Save the mcp.json file. Kiro detects configuration changes automatically — the BookStack tools will be available in your next agent chat or spec session without a full restart. If tools don't appear, open the MCP panel in Kiro settings to check for any startup errors from the server process.

What Kiro Can Do with BookStack

Once connected, Kiro's agent has access to the following BookStack tools:

Tool Description Requires Write?
search_content Full-text search across all books, chapters, and pages No
get_page Retrieve a specific page's content by ID No
get_books / get_book List all books or get details of a specific book No
get_chapters / get_chapter List or retrieve chapters No
get_recent_changes List recently updated content No
export_page Export a page as HTML, PDF, Markdown, or plain text No
create_page Create a new page in a specified book or chapter Yes
update_page Update an existing page's title or content Yes
create_shelf / update_shelf Manage book shelves Yes
create_attachment Attach a link to a page Yes

Example Kiro Prompts

Search docs before implementing something

"Search BookStack for our internal REST API authentication spec, then scaffold a Python client that implements it."

Kiro calls search_content with your query, reads the matching page, then uses that content as context to generate accurate implementation code — no copy-paste needed.

Generate a documentation page from code

"Read the db_backup.sh script I just wrote, then create a BookStack page in the Linux book titled 'Automated DB Backup Script' documenting how it works."

Kiro reads the file, drafts the documentation, and calls create_page with the appropriate book_id. The page appears in BookStack immediately.

Update a page after making changes

"I've changed the firewall rules on the iSeries — find the iSeries network configuration page in BookStack and update it to reflect the new port allowlist."

Kiro uses search_content to locate the page, reads it, then calls update_page with the revised content, preserving everything else on the page.

Auto-update docs via Agent Hook

"When I save any file in scripts/, automatically update the corresponding BookStack runbook page."

Define an Agent Hook in .kiro/hooks/ that fires on file-save events. The hook instructs Kiro to find and update the relevant BookStack page each time you save a script — keeping your runbooks always in sync without manual effort.

Read a runbook to answer a question

"What's the correct process for joining a new Linux VM to our domain? Check the BookStack Linux book."

Kiro searches BookStack, reads the relevant page, and answers from your actual internal documentation rather than generic knowledge.

Tips and Gotchas

  • Write mode is off by default. Don't forget BOOKSTACK_ENABLE_WRITE=true — otherwise create/update calls will silently do nothing or error.
  • Export your env vars before launching Kiro. Kiro reads environment variables at startup. If you add them to your shell profile, open a new terminal session before starting Kiro, or they won't be picked up.
  • Use disabledTools to limit risk. If you want Kiro to read but not write, omit BOOKSTACK_ENABLE_WRITE and also add "disabledTools": ["create_page", "update_page"] to your server config block for an extra layer of protection.
  • Mention BookStack explicitly in your prompt. Kiro won't automatically reach for the BookStack MCP unless the context makes it clear — say "check BookStack" or "search our docs" to guide it.
  • Check the book ID when creating pages. If Kiro creates a page in the wrong book, tell it the correct book name. It will look up the ID via get_books and retry.
  • Don't commit secrets to the repo. Use ${VAR_NAME} references in mcp.json, not literal token values. Add .kiro/settings/mcp.json to .gitignore if it exists at workspace level and your team has different credentials.
  • Token permissions matter. The MCP token acts as the BookStack user you created it under. If that user can't see a book, neither can Kiro.

Troubleshooting

Issue Resolution
BookStack tools don't appear in Kiro Check the Kiro MCP panel for server errors; verify mcp.json is valid JSON; run npx -y bookstack-mcp manually to check for install errors
Authentication error (401) Confirm BOOKSTACK_TOKEN_ID and BOOKSTACK_TOKEN_SECRET are correct; check the token hasn't expired in BookStack
Connection refused / cannot reach BookStack Confirm BOOKSTACK_BASE_URL is reachable from the machine running Kiro; check VPN or firewall if BookStack is internal
Create/update page does nothing Ensure BOOKSTACK_ENABLE_WRITE=true is set in the env block
Environment variables not resolving Make sure variables are exported in your shell before starting Kiro; restart Kiro after adding them
Kiro agent doesn't use BookStack Mention BookStack explicitly in your prompt — e.g. "search our BookStack docs for..."
Search returns no results Ensure BookStack's search index is up to date: php artisan bookstack:regenerate-search

References

No comments to display

Back to top