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

Features

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

Related MCP server: Coda Universal MCP Server

Requirements

• Python ≥ 3.10

• A running INCEpTION instance (tested with INCEpTION 33+) with the REST API enabled (see below)

• uv (recommended) or pip

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.

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):

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

Documents

Annotations

Curation

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

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.