inception-mcp

from RaphFaure

MCP server and CLI for managing INCEpTION projects, documents, and exports through the AERO v1 REST API.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys

inception-mcp

A wrapper around INCEpTION's AERO v1 REST API, exposing corpus management operations as MCP tools and CLI commands.

Annotations are always performed by human annotators inside the INCEpTION interface. This package does not annotate: it handles corpus management tasks (upload, export, monitoring, import) that can be automated or delegated to an agent.

"Upload all .txt files in gutenberg/processed/ to project 1."
"Export annotations for document 42 by user admin in ctsv3 format to data/annot.tsv."

Exposes INCEpTION's AERO v1 REST API as:

MCP tools — callable from any MCP-compatible agent (Claude Code, Claude Desktop, etc.)
CLI — standalone terminal interface, no AI agent required

Both share the same underlying InceptionClient.

Use cases

Scenario	How
Corpus upload at scale	Batch-upload hundreds of documents to a project
Pipeline management	Chain upload → monitor progress → export completed annotations
Progress monitoring	List all documents and their annotation states per user
Export and post-processing	Export ctsv3/XMI annotations and pipe them into a parsing script
Multi-project management	Create, inspect and archive projects without leaving the terminal

Features

Feature	MCP server	CLI
List / create / delete projects	✓	✓
Export / import project ZIP (schema + docs + annotations)	✓	✓
Project progress status	✓	✓
List / upload / delete documents	✓	✓
Batch upload a folder of documents	✓	✓
Export document source	✓	✓
List annotations by user	✓	✓
Export / import annotations (13 formats)	✓	✓
Export all annotations for a project	✓	✓
Delete annotations by user	✓	✓
Export / delete curation layer	✓	✓

Supported export formats: ctsv3, xmi, xmi-struct, conllu, conll2003, conll2006, conll2009, conll2012, text, tcf, jsoncas, jsoncas-struct, nif.

Enabling the INCEpTION REST API

The AERO v1 REST API must be enabled before using this package. Refer to the official INCEpTION documentation for instructions.

Once enabled, the API is reachable at http://<host>:<port>/api/aero/v1. The Swagger UI is available at:

http://<host>:<port>/swagger-ui.html

Authentication uses HTTP Basic Auth with your INCEpTION credentials.

Architecture

inception_mcp/
├── __init__.py      # Public exports: InceptionClient, InceptionError
├── client.py        # InceptionClient — HTTP layer over AERO v1 REST API
├── server.py        # FastMCP server — wraps client as MCP tools
└── cli.py           # argparse CLI — wraps client as shell commands
tests/
└── test_client.py   # Unit tests (22 tests, no INCEpTION instance required)

client.py is the single source of truth for all API calls. Adding a new operation means implementing it once in InceptionClient, then exposing it in server.py (as a @mcp.tool()) and in cli.py (as a new subcommand).

Run tests with:

pip install pytest
pytest tests/

Security notes

Destructive operations are irreversible. delete_project, delete_document, delete_annotations and delete_curation have no undo mechanism in INCEpTION. Always verify IDs before calling them.

The server runs locally and is only reachable from the machine where it is started. Credentials are read from environment variables — never hard-code them in files committed to version control. The .gitignore in this repository excludes .env.

INCEpTION API reference

The full AERO v1 Swagger UI is available at:

http://<your-inception-host>:<port>/swagger-ui.html

License

MIT — you are free to use, modify, and redistribute this software in any project, commercial or not, as long as the original copyright notice is kept.

Copy & paste — that's it

Authentication uses HTTP Basic Auth with your INCEpTION credentials.

 

## Installation

### With uv (recommended)

Before it works, you'll need: INCEPTION_URLINCEPTION_USERINCEPTION_PASSWORD

Requirements

Python ≥ 3.10
A running INCEpTION instance (tested with INCEpTION 33+) with the REST API enabled (see below)
uv (recommended) or pip

Installation

With uv (recommended)

git clone https://github.com/RaphFaure/inception-mcp
cd inception-mcp
uv sync

With pip

git clone https://github.com/RaphFaure/inception-mcp
cd inception-mcp
pip install -e .

Configuration

Connection parameters are read from environment variables (or a .env file at the project root):

Variable	Default	Description
`INCEPTION_URL`	`http://localhost:8080`	Base URL of the INCEpTION instance
`INCEPTION_USER`	`admin`	Username
`INCEPTION_PASSWORD`	(empty)	Password

Create a .env file:

cp .env.example .env
# then edit .env with your credentials

Usage — MCP server

Claude Desktop

Add the following block to your ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "inception": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/inception-mcp", "inception-mcp"],
      "env": {
        "INCEPTION_URL": "http://localhost:8080",
        "INCEPTION_USER": "admin",
        "INCEPTION_PASSWORD": "your_password"
      }
    }
  }
}

Restart Claude Desktop. The INCEpTION tools will appear automatically.

Claude Code (claude.ai/code)

Add the same block under mcpServers in your project's .claude/settings.json or in ~/.claude/settings.json.

Available MCP tools

Projects

Tool	Description
`list_projects`	List all accessible projects
`create_project(name, description?)`	Create a new project
`delete_project(project_id)`	⚠️ Delete a project and all its documents
`export_project_zip(project_id, output_path)`	Export full project as ZIP
`import_project_zip(zip_path)`	Import a project from ZIP
`project_status(project_id)`	Show annotation progress per document

Documents

Tool	Description
`list_documents(project_id)`	List documents in a project
`upload_document(project_id, file_path, fmt?)`	Upload a single file
`batch_upload(project_id, folder_path, fmt?, glob?)`	Upload all files in a folder
`export_document_source(project_id, document_id, output_path, fmt?)`	Export document source
`delete_document(project_id, document_id)`	⚠️ Delete a document

Annotations

Tool	Description
`list_annotations(project_id, document_id)`	List annotations per user
`export_annotations(project_id, document_id, user, fmt?, output_path?)`	Export annotations
`export_all_annotations(project_id, user, output_dir, fmt?)`	Export all docs in a project
`import_annotations(project_id, document_id, user, file_path, fmt?, state?)`	Import annotations
`delete_annotations(project_id, document_id, user)`	⚠️ Delete a user's annotations

Curation

Tool	Description
`export_curation(project_id, document_id, fmt?, output_path?)`	Export curated annotations
`delete_curation(project_id, document_id)`	⚠️ Delete curated annotations

Usage — CLI

# via uv
uv run inception-cli <command>

# or, if installed via pip
inception-cli <command>

Global options

--url       URL INCEpTION  (overrides $INCEPTION_URL)
--user      Username        (overrides $INCEPTION_USER)
--password  Password        (overrides $INCEPTION_PASSWORD)

Commands

# Projects
inception-cli list-projects
inception-cli create-project --name my_project
inception-cli status --project 1
inception-cli export-project --project 1 --out backup.zip
inception-cli import-project --zip backup.zip
inception-cli delete-project --project 1

# Documents
inception-cli list-documents --project 1
inception-cli upload --project 1 --file doc.txt --format text
inception-cli batch-upload --project 1 --folder ./texts --glob "*.txt"
inception-cli export-doc-source --project 1 --doc 42 --out source.txt
inception-cli delete-doc --project 1 --doc 42

# Annotations
inception-cli list-annotations --project 1 --doc 42
inception-cli export --project 1 --doc 42 --user admin --format ctsv3 --out annot.tsv
inception-cli export-all --project 1 --user admin --out-dir ./annotations
inception-cli import-annotations --project 1 --doc 42 --user admin --file annot.tsv
inception-cli delete-annotations --project 1 --doc 42 --user admin

# Curation
inception-cli export-curation --project 1 --doc 42 --format ctsv3 --out curation.tsv
inception-cli delete-curation --project 1 --doc 42