inception-mcp

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

"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."

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

The AERO v1 REST API must be enabled before using this package. Refer to theofficial INCEpTION documentationfor instructions.

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

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

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

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

{ "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.

Add the same block undermcpServersin your project's.claude/settings.jsonor in~/.claude/settings.json.

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

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

# 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

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.pyis the single source of truth for all API calls. Adding a new operation means implementing it once inInceptionClient, then exposing it inserver.py(as a@mcp.tool()) and incli.py(as a new subcommand).

Destructive operations are irreversible.delete_project,delete_document,delete_annotationsanddelete_curationhave 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.gitignorein this repository excludes.env.

The full AERO v1 Swagger UI is available at:

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

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.

Bible Glide account context, Daily Scripture, church activity, and Bible chat.