iceberg-mcp-server
iceberg-mcp-server is an MCP Server for Apache Iceberg, enabling users to read, query, and manipulate data within Iceberg catalogs. It supports reading and data manipulation using catalog types supported by PyIceberg, and supports SQL queries using catalog types compatible with DuckDB.
Quickstart
Installation
With uv, installation is easy, the only command you need to run is:
uvx iceberg-mcp-server
This will automatically install and run the latest version of iceberg-mcp-server published to PyPI. Alternative Python package runners like pipx are also supported. Once installed, iceberg-mcp-server can be used with any agent that supports STDIO-based MCP servers. For example, with Github Copilot mcp.json:
"servers": {
"iceberg-mcp-server": {
"command": "uvx",
"args": [
"iceberg-mcp-server"
],
}
}
Configuration
.pyiceberg.yaml File
iceberg-mcp-server supports the PyIceberg configuration methods. .pyiceberg.yaml is the recommended persistent method of configuration. For example, to connect to a standard REST-based Iceberg catalog with ~/.pyiceberg.yaml:
catalog:
default: # iceberg-mcp-server loads the catalog named "default" if not in env vars
uri: <catalog-uri>
token: <catalog-token>
warehouse: <warehouse>
Environment Variables
One of the other PyIceberg configuration methods is setting specific environment variables, which iceberg-mcp-server supports as well. There are also environment variables specific to iceberg-mcp-server that can be set:
ICEBERG_CATALOG="default"
OTEL_EXPORTER_OTLP_ENDPOINT="https://..."
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://.../v1/traces"
SENTRY_DSN="https://<sentry-key>@o<organization-id>.ingest.us.sentry.io/<project-id>"
ICEBERG_CATALOGallows you to set which catalog will be loaded. By default, the catalog nameddefaultwill be loaded based on PyIceberg behavior.- Optionally, you may choose to send telemetry via OpenTelemetry OTLP to a specific endpoint. This will send traces generated by the FastMCP OTel integration, Requests OTel integration, and botocore OTel ingration to the specified OTLP endpoint.
- Alternatively, you may send telemetry to Sentry by specifying a
SENTRY_DSN. This will send traces, profiles, logs, and default PII to Sentry, as well as enable the Sentry MCP integration.
Local Development
Building and Running
This project uses uv for package management and builds. Once this repository has been cloned, running the local development version of iceberg-mcp-server only requires a single command:
uv run iceberg-mcp-server
An Iceberg catalog still needs to be configured, but then it can be integrated into any agent that supports STDIO-based MCP servers as long as the agent is ran from the repository root directory.
Testing
This repository uses pytest for test running, although the tests themselves are structured in the unittest format. Running tests involves invoking pytest like any other project. If you use VS Code or a fork for development, the VS Code Python Extension will enable automatic test discovery and running in the Testing sidebar. Tests will also be run with coverage in the integration workflow.
Linting and Formatting
iceberg-mcp-server uses Ruff and ty for linting, formatting, and type checking. The standard commands to run are:
ruff check --fix # linting
ruff format # formatting
ty check # type checking
The Ruff configuration is found in pyproject.toml, and all autofixable issues will be autofixed. If you use VS Code or a fork for development, the VS Code Ruff Extension and VS Code ty Extension will enable viewing issues from Ruff and ty within your editor. Additionally, Ruff, ty, and CodeQL analysis will be run in the integration workflow.
1 maintainer
Metadata
1 maintainer
Release files for iceberg-mcp-server 0.2.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| iceberg_mcp_server-0.2.6.tar.gz | 8.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| iceberg_mcp_server-0.2.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 20.2 kB
Release files / iceberg_mcp_server-0.2.6.tar.gz
| Download URL | iceberg_mcp_server-0.2.6.tar.gz |
|---|---|
| Size | 8.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6728deaec23ca13618aaaf42096f20e68598f075ea70066a8b2368958d1cbfb2
|
|
BLAKE2b-256 checksum How to use checksums |
aa2cc1e34acd2b873642dce365d37eb9f2063b53824e37461472b63da876ba90
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency logRelease files / iceberg_mcp_server-0.2.6-py3-none-any.whl
| Download URL | iceberg_mcp_server-0.2.6-py3-none-any.whl |
|---|---|
| Size | 11.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3b0f8b313df121142c128f4439a8fb495d3896e211480b5553d82a803515f006
|
|
BLAKE2b-256 checksum How to use checksums |
49ac504bdbac3dddd0ccc608ffb5afa0bc6c2853585c2782a23a394ae8a640a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency log
