Arcticdb MCP

1<div align="center">
2  <h1>arcticdb-mcp</h1>
3  <p><strong>An MCP server for structured read/write access to ArcticDB.</strong></p>
4  <p>
5    <a href="https://pypi.org/project/arcticdb-mcp/"><img src="https://img.shields.io/pypi/v/arcticdb-mcp.svg" alt="PyPI" /></a>
6    <a href="https://pypi.org/project/arcticdb-mcp/"><img src="https://img.shields.io/pypi/pyversions/arcticdb-mcp.svg" alt="Python Versions" /></a>
7    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
8  </p>
9  <p>
10    <a href="#overview">Overview</a> •
11    <a href="#demo-video">Demo</a> •
12    <a href="#quickstart">Quick Start</a> •
13    <a href="#configuration">Configuration</a> •
14    <a href="#tools">Tools</a> •
15    <a href="#development">Development</a>
16  </p>
17</div>
18
19## Overview
20
21`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`.
22
23## Table of Contents
24
25- [Demo Video](#demo-video)
26- [Quickstart](#quickstart)
27- [Installation](#installation)
28- [Configuration](#configuration)
29- [Run Modes](#run-modes)
30- [Tools](#tools)
31- [Example Prompts](#example-prompts)
32- [Development](#development)
33- [Community Backlog](#community-backlog)
34- [Contributing](#contributing)
35- [License](#license)
36
37## Demo Video
38
39Watch the live `watch db` demo:
40
41https://github.com/user-attachments/assets/dd81f229-e1f9-46e6-8e79-7c7252bc25c6
42
43## Quickstart
44
451. Install and run with `uvx` (recommended):
46
47```bash
48uvx arcticdb-mcp
49```
50
512. Configure your MCP client (Claude Desktop / Cursor / Windsurf / Continue):
52
53```json
54{
55  "mcpServers": {
56    "arcticdb": {
57      "command": "uvx",
58      "args": ["arcticdb-mcp"],
59      "env": {
60        "ARCTICDB_URI": "lmdb:///path/to/your/database"
61      }
62    }
63  }
64}
65```
66
673. Ask your assistant:
68
69- "Show me the last 5 rows of AAPL in library finance"
70- "Create a snapshot of finance before I update symbols"
71- "List versions for symbol ES_intraday"
72
73## Installation
74
75Choose one:
76
77```bash
78# Recommended
79uvx arcticdb-mcp
80
81# Or
82pipx install arcticdb-mcp
83
84# Or
85pip install arcticdb-mcp
86```
87
88Python requirement: `>=3.9`
89
90## Configuration
91
92Set `ARCTICDB_URI` in MCP client config or environment.
93
94### URI examples
95
96- Local LMDB (Linux/macOS): `lmdb:///path/to/db`
97- Local LMDB (Windows): `lmdb://C:/path/to/db`
98- AWS S3: `s3://s3.amazonaws.com:bucket?region=us-east-1&access=KEY&secret=SECRET`
99- Azure Blob: `azure://AccountName=X;AccountKey=Y;Container=Z`
100- S3-compatible (MinIO, etc.): `s3://your-endpoint:bucket?access=KEY&secret=SECRET`
101
102You can also use a `.env` file:
103
104```env
105ARCTICDB_URI=lmdb:///path/to/db
106```
107
108## Run Modes
109
110### stdio (default)
111
112This is the default mode used by desktop MCP clients.
113
114```bash
115ARCTICDB_URI=lmdb:///path/to/db python -m arcticdb_mcp
116```
117
118### HTTP / SSE
119
120Set `ARCTICDB_MCP_PORT` to run over HTTP/SSE:
121
122```bash
123ARCTICDB_URI=lmdb:///path/to/db ARCTICDB_MCP_PORT=8000 python -m arcticdb_mcp
124```
125
126Endpoint:
127
128```text
129http://localhost:8000/sse
130```
131
132## Tools
133
134Current server exposes 48 tools.
135
136### Arctic and Libraries
137
138| Tool | File | What it does |
139|---|---|---|
140| `get_uri` | `arcticdb_mcp/tools/arctic_tools.py` | Return the ArcticDB URI used by this MCP server connection. |
141| `describe` | `arcticdb_mcp/tools/arctic_tools.py` | Return a compact summary of the ArcticDB store. |
142| `modify_library_option` | `arcticdb_mcp/tools/arctic_tools.py` | Modify a configurable library option. |
143| `list_libraries` | `arcticdb_mcp/tools/library_tools.py` | List all libraries in the Arctic instance. |
144| `create_library` | `arcticdb_mcp/tools/library_tools.py` | Create a new library with the given name. |
145| `delete_library` | `arcticdb_mcp/tools/library_tools.py` | Delete a library and all its underlying data permanently. |
146| `library_exists` | `arcticdb_mcp/tools/library_tools.py` | Check whether a library with the given name exists. |
147| `get_library` | `arcticdb_mcp/tools/library_tools.py` | Return the name and full list of symbols stored in a library. |
148| `get_library_options` | `arcticdb_mcp/tools/maintenance_tools.py` | Return non-enterprise library options. |
149| `get_enterprise_options` | `arcticdb_mcp/tools/maintenance_tools.py` | Return enterprise library options. |
150
151### Symbols
152
153| Tool | File | What it does |
154|---|---|---|
155| `list_symbols` | `arcticdb_mcp/tools/symbol_tools.py` | List all symbol names stored in the given library. |
156| `symbol_exists` | `arcticdb_mcp/tools/symbol_tools.py` | Check whether a symbol exists in the given library. |
157| `read_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Read a symbol's full data as row records with index included. |
158| `head_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Return the first `n` rows of a symbol (default 5). |
159| `tail_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Return the last `n` rows of a symbol (default 5). |
160| `write_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Write data to a symbol, creating a new version. |
161| `append_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Append rows to an existing symbol, creating a new version. |
162| `update_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Update a date range of a timeseries symbol, creating a new version. |
163| `delete_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Delete a symbol and all its versions from the library. |
164| `delete_data_in_range` | `arcticdb_mcp/tools/symbol_tools.py` | Delete rows within a date range from a timeseries symbol, creating a new version. |
165| `get_symbol_info` | `arcticdb_mcp/tools/symbol_tools.py` | Return schema, row count, date range, and metadata summary for a symbol. |
166| `list_versions` | `arcticdb_mcp/tools/symbol_tools.py` | List all versions of a symbol with version number and write timestamp. |
167| `read_metadata` | `arcticdb_mcp/tools/symbol_tools.py` | Read only metadata for a symbol without loading its data. |
168| `write_metadata` | `arcticdb_mcp/tools/symbol_tools.py` | Update metadata for a symbol without modifying its data. |
169
170### Batch Operations
171
172| Tool | File | What it does |
173|---|---|---|
174| `write_batch` | `arcticdb_mcp/tools/batch_tools.py` | Write multiple symbols in one call. |
175| `append_batch` | `arcticdb_mcp/tools/batch_tools.py` | Append to multiple symbols in one call. |
176| `update_batch` | `arcticdb_mcp/tools/batch_tools.py` | Update multiple symbols in one call. |
177| `delete_batch` | `arcticdb_mcp/tools/batch_tools.py` | Delete multiple symbols or symbol versions in one call. |
178| `read_batch` | `arcticdb_mcp/tools/batch_tools.py` | Read multiple symbols in one call. |
179| `read_metadata_batch` | `arcticdb_mcp/tools/batch_tools.py` | Read metadata for multiple symbols in one call. |
180| `get_description_batch` | `arcticdb_mcp/tools/batch_tools.py` | Get schema/description for multiple symbols in one call. |
181| `write_metadata_batch` | `arcticdb_mcp/tools/batch_tools.py` | Write metadata for multiple symbols in one call. |
182| `write_pickle` | `arcticdb_mcp/tools/batch_tools.py` | Write arbitrary pickle-serializable data to a symbol. |
183| `write_pickle_batch` | `arcticdb_mcp/tools/batch_tools.py` | Write multiple pickle-serializable payloads in one call. |
184
185### Snapshots
186
187| Tool | File | What it does |
188|---|---|---|
189| `create_snapshot` | `arcticdb_mcp/tools/snapshot_tools.py` | Create a named snapshot of the current library state. |
190| `list_snapshots` | `arcticdb_mcp/tools/snapshot_tools.py` | List the names of all snapshots in a library. |
191| `delete_snapshot` | `arcticdb_mcp/tools/snapshot_tools.py` | Delete a named snapshot from a library. |
192| `read_symbol_from_snapshot` | `arcticdb_mcp/tools/snapshot_tools.py` | Read a symbol as it existed when a snapshot was created. |
193
194### Query Helpers
195
196| Tool | File | What it does |
197|---|---|---|
198| `query_filter` | `arcticdb_mcp/tools/query_tools.py` | Filter rows using conditions. |
199| `query_filter_isin` | `arcticdb_mcp/tools/query_tools.py` | Filter rows where a column value is in a list. |
200| `query_groupby` | `arcticdb_mcp/tools/query_tools.py` | Group by a column and aggregate. |
201| `query_date_range` | `arcticdb_mcp/tools/query_tools.py` | Filter rows by date range on a datetime-indexed symbol. |
202| `query_resample` | `arcticdb_mcp/tools/query_tools.py` | Resample a datetime-indexed symbol and aggregate. |
203
204### Maintenance
205
206| Tool | File | What it does |
207|---|---|---|
208| `reload_symbol_list` | `arcticdb_mcp/tools/maintenance_tools.py` | Force a symbol-list cache reload for a library. |
209| `compact_symbol_list` | `arcticdb_mcp/tools/maintenance_tools.py` | Compact symbol-list cache into a single key in storage. |
210| `is_symbol_fragmented` | `arcticdb_mcp/tools/maintenance_tools.py` | Check whether compaction would reduce segment count for a symbol. |
211| `defragment_symbol_data` | `arcticdb_mcp/tools/maintenance_tools.py` | Defragment symbol data by compacting fragmented row-sliced segments. |
212| `prune_previous_versions` | `arcticdb_mcp/tools/maintenance_tools.py` | Remove non-snapshotted symbol versions except the latest one. |
213
214## Example Prompts
215
216- "Read symbol NVDA from library finance"
217- "Filter NVDA where price > 500 and volume >= 1000"
218- "Resample ES_intraday to 5min and aggregate price mean, volume sum"
219- "Write metadata owner=research to symbol ES_intraday"
220- "Delete data in range for ES_intraday from 2024-01-01 to 2024-01-05"
221
222## Development
223
224```bash
225git clone https://github.com/YMuskrat/arcticdb-mcp
226cd arcticdb-mcp
227pip install -e .
228```
229
230Run locally:
231
232```bash
233ARCTICDB_URI=lmdb:///path/to/db python -m arcticdb_mcp
234```
235
236Test with MCP Inspector:
237
238```bash
239ARCTICDB_URI=lmdb:///tmp/test_db npx @modelcontextprotocol/inspector python -m arcticdb_mcp
240```
241
242## Community Backlog
243
244These ArcticDB capabilities are intentionally left open for contributors:
245
246- `stage`
247- `finalize_staged_data`
248- `sort_and_finalize_staged_data`
249- `delete_staged_data`
250- `get_staged_symbols`
251- `read_batch_and_join`
252- `admin_tools`
253
254## Contributing
255
256See [CONTRIBUTING.md](CONTRIBUTING.md).
257
258## License
259
260MIT
261
262