ai-kb-mcp

AI KB MCP Server

⚠️ Deprecated

AI KB now ships a built-in MCP server: create endpoints under "Settings → Publish & Integrations → MCP Server", each with its own token, knowledge-base scope and tool list, and connect clients to /mcp/<endpoint_id> over Streamable HTTP. Prefer the built-in endpoint; this Python package may be removed in a future release.

A Model Context Protocol (MCP) server that gives access to the AI KB knowledge management API.

Quick start

We recommend following the MCP configuration guide instead of the steps below.

1. Install

pip install ai-kb-mcp
# Or run it with uvx without installing
uvx --from ai-kb-mcp ai-kb-mcp-server

The distribution is ai-kb-mcp; its command-line entry points are ai-kb-mcp-server and ai-kb-server. The MCP packages on PyPI under the upstream project's name belong to that project and read its own variable names, not AIKB_*.

2. Set environment variables

# Linux/macOS
export AIKB_BASE_URL="http://localhost:8080/api/v1"
export AIKB_API_KEY="your_api_key_here"

# Windows PowerShell
$env:AIKB_BASE_URL="http://localhost:8080/api/v1"
$env:AIKB_API_KEY="your_api_key_here"

# Windows CMD
set AIKB_BASE_URL=http://localhost:8080/api/v1
set AIKB_API_KEY=your_api_key_here

Create the API key under Settings → Publish & Integrations → API Integration → API Keys.

3. Run the server

ai-kb-mcp-server                      # stdio, for MCP clients that launch the server
ai-kb-mcp-server --help               # show help
ai-kb-mcp-server --check-only         # check the environment configuration only
ai-kb-mcp-server --verbose            # enable verbose logging
ai-kb-mcp-server --version            # show the version

Network transports

MCP_SERVER_AUTH_TOKEN=change_me ai-kb-mcp-server --transport http --host 0.0.0.0 --port 8000

The Streamable HTTP endpoint is /mcp; the SSE transport serves /sse and /sse/messages/. Clients send Authorization: Bearer <token> or X-MCP-Auth-Token: <token>.

Run from a source checkout

From the mcp-server/ directory of the repository:

pip install -r requirements.txt
python main.py                        # same options as ai-kb-mcp-server

# Or install the checkout
pip install .                         # pip install -e . for development
uvx --from . ai-kb-mcp-server         # without installing

python run_server.py, python run.py, python aikb_mcp_server.py and python -m aikb_mcp_server also start the server.

Build distribution packages

pip install build
python -m build

Test the module

python test_module.py

Features

The MCP server provides these tools:

Workspace management

• create_tenant - create a workspace
• list_tenants - list all workspaces

Knowledge base management

• create_knowledge_base - create a knowledge base
• list_knowledge_bases - list knowledge bases
• get_knowledge_base - get knowledge base details
• list_shared_knowledge_bases - list knowledge bases shared with you
• delete_knowledge_base - delete a knowledge base
• hybrid_search - hybrid search

Knowledge management

• create_knowledge_from_file - create knowledge from a local file
• create_knowledge_from_url - create knowledge from a URL
• create_knowledge_from_text - create knowledge from text
• update_knowledge_from_text - update manual Markdown knowledge, re-index it or save it as a draft
• list_knowledge - list knowledge
• get_knowledge - get knowledge details
• delete_knowledge - delete knowledge

Model management

• create_model - create a model
• list_models - list models
• get_model - get model details

Session management

• create_session - create a chat session
• get_session - get session details
• list_sessions - list sessions
• delete_session - delete a session

Chat

• chat - send a chat message
• agent_chat - call an agent for multi-step retrieval and tool calls

Both chat tools assemble events on SSE blank-line boundaries, so one event can span several data: lines. An event still open when the connection ends (no blank line seen yet) is dropped. Each event's data buffer is capped at 8 MiB; exceeding the cap returns an error and closes the response connection.

Agents

• list_agents - list agents
• get_agent - get agent details

Chunk management

• list_chunks - list knowledge chunks
• delete_chunk - delete a knowledge chunk

Wiki

• wiki_search - search a knowledge base's wiki pages
• wiki_read_page - read one wiki page by slug
• wiki_index_view - show a knowledge base's wiki index

Troubleshooting

If you hit import errors, make sure that:

1. All required dependencies are installed
2. Your Python version is compatible (3.11 or newer)
3. No file name conflicts (do not name a file mcp.py)

Local upload directory boundary

All transports, including stdio, restrict local file uploads to the working directory by default. Set MCP_ALLOWED_UPLOAD_DIRS to a comma-separated list of trusted absolute directories when additional roots are needed. Starting in a filesystem root requires an explicit directory configuration. Paths and symbolic links resolving outside the selected roots are rejected.