<div align="center">
  <h1>arcticdb-mcp</h1>
  <p><strong>An MCP server for structured read/write access to ArcticDB.</strong></p>
  <p>
    <a href="https://pypi.org/project/arcticdb-mcp/"><img src="https://img.shields.io/pypi/v/arcticdb-mcp.svg" alt="PyPI" /></a>
    <a href="https://pypi.org/project/arcticdb-mcp/"><img src="https://img.shields.io/pypi/pyversions/arcticdb-mcp.svg" alt="Python Versions" /></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
  </p>
  <p>
    <a href="#overview">Overview</a> •
    <a href="#demo-video">Demo</a> •
    <a href="#quickstart">Quick Start</a> •
    <a href="#configuration">Configuration</a> •
    <a href="#tools">Tools</a> •
    <a href="#development">Development</a>
  </p>
</div>

## Overview

`arcticdb-mcp` turns [ArcticDB](https://github.com/man-group/ArcticDB) into an AI data copilot. Assistants can automate symbol updates, batch jobs, and time-series queries while built-in versioning protects every change. Go from question to data change in minutes, not scripts, with full traceability. You can also design your own workflows on top of `arcticdb-mcp`.

## Table of Contents

- [Demo Video](#demo-video)
- [Quickstart](#quickstart)
- [Installation](#installation)
- [Configuration](#configuration)
- [Run Modes](#run-modes)
- [Tools](#tools)
- [Example Prompts](#example-prompts)
- [Development](#development)
- [Community Backlog](#community-backlog)
- [Contributing](#contributing)
- [License](#license)

## Demo Video

Watch the live `watch db` demo:

https://github.com/user-attachments/assets/dd81f229-e1f9-46e6-8e79-7c7252bc25c6

## Quickstart

1. Install and run with `uvx` (recommended):

```bash
uvx arcticdb-mcp
```

2. Configure your MCP client (Claude Desktop / Cursor / Windsurf / Continue):

```json
{
  "mcpServers": {
    "arcticdb": {
      "command": "uvx",
      "args": ["arcticdb-mcp"],
      "env": {
        "ARCTICDB_URI": "lmdb:///path/to/your/database"
      }
    }
  }
}
```

3. Ask your assistant:

- "Show me the last 5 rows of AAPL in library finance"
- "Create a snapshot of finance before I update symbols"
- "List versions for symbol ES_intraday"

## Installation

Choose one:

```bash
# Recommended
uvx arcticdb-mcp

# Or
pipx install arcticdb-mcp

# Or
pip install arcticdb-mcp
```

Python requirement: `>=3.9`

## Configuration

Set `ARCTICDB_URI` in MCP client config or environment.

### URI examples

- Local LMDB (Linux/macOS): `lmdb:///path/to/db`
- Local LMDB (Windows): `lmdb://C:/path/to/db`
- AWS S3: `s3://s3.amazonaws.com:bucket?region=us-east-1&access=KEY&secret=SECRET`
- Azure Blob: `azure://AccountName=X;AccountKey=Y;Container=Z`
- S3-compatible (MinIO, etc.): `s3://your-endpoint:bucket?access=KEY&secret=SECRET`

You can also use a `.env` file:

```env
ARCTICDB_URI=lmdb:///path/to/db
```

## Run Modes

### stdio (default)

This is the default mode used by desktop MCP clients.

```bash
ARCTICDB_URI=lmdb:///path/to/db python -m arcticdb_mcp
```

### HTTP / SSE

Set `ARCTICDB_MCP_PORT` to run over HTTP/SSE:

```bash
ARCTICDB_URI=lmdb:///path/to/db ARCTICDB_MCP_PORT=8000 python -m arcticdb_mcp
```

Endpoint:

```text
http://localhost:8000/sse
```

## Tools

Current server exposes 48 tools.

### Arctic and Libraries

| Tool | File | What it does |
|---|---|---|
| `get_uri` | `arcticdb_mcp/tools/arctic_tools.py` | Return the ArcticDB URI used by this MCP server connection. |
| `describe` | `arcticdb_mcp/tools/arctic_tools.py` | Return a compact summary of the ArcticDB store. |
| `modify_library_option` | `arcticdb_mcp/tools/arctic_tools.py` | Modify a configurable library option. |
| `list_libraries` | `arcticdb_mcp/tools/library_tools.py` | List all libraries in the Arctic instance. |
| `create_library` | `arcticdb_mcp/tools/library_tools.py` | Create a new library with the given name. |
| `delete_library` | `arcticdb_mcp/tools/library_tools.py` | Delete a library and all its underlying data permanently. |
| `library_exists` | `arcticdb_mcp/tools/library_tools.py` | Check whether a library with the given name exists. |
| `get_library` | `arcticdb_mcp/tools/library_tools.py` | Return the name and full list of symbols stored in a library. |
| `get_library_options` | `arcticdb_mcp/tools/maintenance_tools.py` | Return non-enterprise library options. |
| `get_enterprise_options` | `arcticdb_mcp/tools/maintenance_tools.py` | Return enterprise library options. |

### Symbols

| Tool | File | What it does |
|---|---|---|
| `list_symbols` | `arcticdb_mcp/tools/symbol_tools.py` | List all symbol names stored in the given library. |
| `symbol_exists` | `arcticdb_mcp/tools/symbol_tools.py` | Check whether a symbol exists in the given library. |
| `read_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Read a symbol's full data as row records with index included. |
| `head_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Return the first `n` rows of a symbol (default 5). |
| `tail_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Return the last `n` rows of a symbol (default 5). |
| `write_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Write data to a symbol, creating a new version. |
| `append_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Append rows to an existing symbol, creating a new version. |
| `update_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Update a date range of a timeseries symbol, creating a new version. |
| `delete_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Delete a symbol and all its versions from the library. |
| `delete_data_in_range` | `arcticdb_mcp/tools/symbol_tools.py` | Delete rows within a date range from a timeseries symbol, creating a new version. |
| `get_symbol_info` | `arcticdb_mcp/tools/symbol_tools.py` | Return schema, row count, date range, and metadata summary for a symbol. |
| `list_versions` | `arcticdb_mcp/tools/symbol_tools.py` | List all versions of a symbol with version number and write timestamp. |
| `read_metadata` | `arcticdb_mcp/tools/symbol_tools.py` | Read only metadata for a symbol without loading its data. |
| `write_metadata` | `arcticdb_mcp/tools/symbol_tools.py` | Update metadata for a symbol without modifying its data. |

### Batch Operations

| Tool | File | What it does |
|---|---|---|
| `write_batch` | `arcticdb_mcp/tools/batch_tools.py` | Write multiple symbols in one call. |
| `append_batch` | `arcticdb_mcp/tools/batch_tools.py` | Append to multiple symbols in one call. |
| `update_batch` | `arcticdb_mcp/tools/batch_tools.py` | Update multiple symbols in one call. |
| `delete_batch` | `arcticdb_mcp/tools/batch_tools.py` | Delete multiple symbols or symbol versions in one call. |
| `read_batch` | `arcticdb_mcp/tools/batch_tools.py` | Read multiple symbols in one call. |
| `read_metadata_batch` | `arcticdb_mcp/tools/batch_tools.py` | Read metadata for multiple symbols in one call. |
| `get_description_batch` | `arcticdb_mcp/tools/batch_tools.py` | Get schema/description for multiple symbols in one call. |
| `write_metadata_batch` | `arcticdb_mcp/tools/batch_tools.py` | Write metadata for multiple symbols in one call. |
| `write_pickle` | `arcticdb_mcp/tools/batch_tools.py` | Write arbitrary pickle-serializable data to a symbol. |
| `write_pickle_batch` | `arcticdb_mcp/tools/batch_tools.py` | Write multiple pickle-serializable payloads in one call. |

### Snapshots

| Tool | File | What it does |
|---|---|---|
| `create_snapshot` | `arcticdb_mcp/tools/snapshot_tools.py` | Create a named snapshot of the current library state. |
| `list_snapshots` | `arcticdb_mcp/tools/snapshot_tools.py` | List the names of all snapshots in a library. |
| `delete_snapshot` | `arcticdb_mcp/tools/snapshot_tools.py` | Delete a named snapshot from a library. |
| `read_symbol_from_snapshot` | `arcticdb_mcp/tools/snapshot_tools.py` | Read a symbol as it existed when a snapshot was created. |

### Query Helpers

| Tool | File | What it does |
|---|---|---|
| `query_filter` | `arcticdb_mcp/tools/query_tools.py` | Filter rows using conditions. |
| `query_filter_isin` | `arcticdb_mcp/tools/query_tools.py` | Filter rows where a column value is in a list. |
| `query_groupby` | `arcticdb_mcp/tools/query_tools.py` | Group by a column and aggregate. |
| `query_date_range` | `arcticdb_mcp/tools/query_tools.py` | Filter rows by date range on a datetime-indexed symbol. |
| `query_resample` | `arcticdb_mcp/tools/query_tools.py` | Resample a datetime-indexed symbol and aggregate. |

### Maintenance

| Tool | File | What it does |
|---|---|---|
| `reload_symbol_list` | `arcticdb_mcp/tools/maintenance_tools.py` | Force a symbol-list cache reload for a library. |
| `compact_symbol_list` | `arcticdb_mcp/tools/maintenance_tools.py` | Compact symbol-list cache into a single key in storage. |
| `is_symbol_fragmented` | `arcticdb_mcp/tools/maintenance_tools.py` | Check whether compaction would reduce segment count for a symbol. |
| `defragment_symbol_data` | `arcticdb_mcp/tools/maintenance_tools.py` | Defragment symbol data by compacting fragmented row-sliced segments. |
| `prune_previous_versions` | `arcticdb_mcp/tools/maintenance_tools.py` | Remove non-snapshotted symbol versions except the latest one. |

## Example Prompts

- "Read symbol NVDA from library finance"
- "Filter NVDA where price > 500 and volume >= 1000"
- "Resample ES_intraday to 5min and aggregate price mean, volume sum"
- "Write metadata owner=research to symbol ES_intraday"
- "Delete data in range for ES_intraday from 2024-01-01 to 2024-01-05"

## Development

```bash
git clone https://github.com/YMuskrat/arcticdb-mcp
cd arcticdb-mcp
pip install -e .
```

Run locally:

```bash
ARCTICDB_URI=lmdb:///path/to/db python -m arcticdb_mcp
```

Test with MCP Inspector:

```bash
ARCTICDB_URI=lmdb:///tmp/test_db npx @modelcontextprotocol/inspector python -m arcticdb_mcp
```

## Community Backlog

These ArcticDB capabilities are intentionally left open for contributors:

- `stage`
- `finalize_staged_data`
- `sort_and_finalize_staged_data`
- `delete_staged_data`
- `get_staged_symbols`
- `read_batch_and_join`
- `admin_tools`

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT