Skip to content
Back to search

arcticdb_mcp

MCP server for ArcticDB

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ymuskrat--arcticdb-mcp/badge.svg)](/listings/ymuskrat--arcticdb-mcp)

HTML

<a href="/listings/ymuskrat--arcticdb-mcp"><img src="/api/listings/ymuskrat--arcticdb-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

uvx arcticdb-mcp

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

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 291 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  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. ## Overview
  19. `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`.
  20. ## Table of Contents
  21. - [Demo Video](#demo-video)
  22. - [Quickstart](#quickstart)
  23. - [Installation](#installation)
  24. - [Configuration](#configuration)
  25. - [Run Modes](#run-modes)
  26. - [Tools](#tools)
  27. - [Example Prompts](#example-prompts)
  28. - [Development](#development)
  29. - [Community Backlog](#community-backlog)
  30. - [Contributing](#contributing)
  31. - [License](#license)
  32. ## Demo Video
  33. Watch the live `watch db` demo:
  34. https://github.com/user-attachments/assets/dd81f229-e1f9-46e6-8e79-7c7252bc25c6
  35. ## Quickstart
  36. 1. Install and run with `uvx` (recommended):
  37. ```bash
  38. uvx arcticdb-mcp
  39. ```
  40. 2. Configure your MCP client (Claude Desktop / Cursor / Windsurf / Continue):
  41. ```json
  42. {
  43. "mcpServers": {
  44. "arcticdb": {
  45. "command": "uvx",
  46. "args": ["arcticdb-mcp"],
  47. "env": {
  48. "ARCTICDB_URI": "lmdb:///path/to/your/database"
  49. }
  50. }
  51. }
  52. }
  53. ```
  54. 3. Ask your assistant:
  55. - "Show me the last 5 rows of AAPL in library finance"
  56. - "Create a snapshot of finance before I update symbols"
  57. - "List versions for symbol ES_intraday"
  58. ## Installation
  59. Choose one:
  60. ```bash
  61. # Recommended
  62. uvx arcticdb-mcp
  63. # Or
  64. pipx install arcticdb-mcp
  65. # Or
  66. pip install arcticdb-mcp
  67. ```
  68. Python requirement: `>=3.9`
  69. ## Configuration
  70. Set `ARCTICDB_URI` in MCP client config or environment.
  71. ### URI examples
  72. - Local LMDB (Linux/macOS): `lmdb:///path/to/db`
  73. - Local LMDB (Windows): `lmdb://C:/path/to/db`
  74. - AWS S3: `s3://s3.amazonaws.com:bucket?region=us-east-1&access=KEY&secret=SECRET`
  75. - Azure Blob: `azure://AccountName=X;AccountKey=Y;Container=Z`
  76. - S3-compatible (MinIO, etc.): `s3://your-endpoint:bucket?access=KEY&secret=SECRET`
  77. You can also use a `.env` file:
  78. ```env
  79. ARCTICDB_URI=lmdb:///path/to/db
  80. ```
  81. ## Run Modes
  82. ### stdio (default)
  83. This is the default mode used by desktop MCP clients.
  84. ```bash
  85. ARCTICDB_URI=lmdb:///path/to/db python -m arcticdb_mcp
  86. ```
  87. ### HTTP / SSE
  88. Set `ARCTICDB_MCP_PORT` to run over HTTP/SSE:
  89. Use an integer from `1` to `65535`. An unset or empty value selects stdio.
  90. ```bash
  91. ARCTICDB_URI=lmdb:///path/to/db ARCTICDB_MCP_PORT=8000 python -m arcticdb_mcp
  92. ```
  93. Endpoint:
  94. ```text
  95. http://localhost:8000/sse
  96. ```
  97. ## Tools
  98. Current server exposes 49 tools.
  99. ### Arctic and Libraries
  100. | Tool | File | What it does |
  101. |---|---|---|
  102. | `get_uri` | `arcticdb_mcp/tools/arctic_tools.py` | Return the ArcticDB URI used by this MCP server connection. |
  103. | `describe` | `arcticdb_mcp/tools/arctic_tools.py` | Return a compact summary of the ArcticDB store. |
  104. | `modify_library_option` | `arcticdb_mcp/tools/arctic_tools.py` | Modify a configurable library option. |
  105. | `list_libraries` | `arcticdb_mcp/tools/library_tools.py` | List all libraries in the Arctic instance. |
  106. | `create_library` | `arcticdb_mcp/tools/library_tools.py` | Create a new library with the given name. |
  107. | `delete_library` | `arcticdb_mcp/tools/library_tools.py` | Delete a library and all its underlying data permanently. |
  108. | `library_exists` | `arcticdb_mcp/tools/library_tools.py` | Check whether a library with the given name exists. |
  109. | `get_library` | `arcticdb_mcp/tools/library_tools.py` | Return the name and full list of symbols stored in a library. |
  110. | `get_library_options` | `arcticdb_mcp/tools/maintenance_tools.py` | Return non-enterprise library options. |
  111. | `get_enterprise_options` | `arcticdb_mcp/tools/maintenance_tools.py` | Return enterprise library options. |
  112. ### Symbols
  113. | Tool | File | What it does |
  114. |---|---|---|
  115. | `list_symbols` | `arcticdb_mcp/tools/symbol_tools.py` | List all symbol names stored in the given library. |
  116. | `symbol_exists` | `arcticdb_mcp/tools/symbol_tools.py` | Check whether a symbol exists in the given library. |
  117. | `read_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Read a symbol's full data as row records with index included. |
  118. | `read_symbol_page` | `arcticdb_mcp/tools/symbol_tools.py` | Read paginated slice of a symbol with backend row-slicing, column projection, and version consistency. |
  119. | `head_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Return the first `n` rows of a symbol (default 5). |
  120. | `tail_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Return the last `n` rows of a symbol (default 5). |
  121. | `write_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Write data to a symbol, creating a new version. |
  122. | `append_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Append rows to an existing symbol, creating a new version. |
  123. | `update_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Update a date range of a timeseries symbol, creating a new version. |
  124. | `delete_symbol` | `arcticdb_mcp/tools/symbol_tools.py` | Delete a symbol and all its versions from the library. |
  125. | `delete_data_in_range` | `arcticdb_mcp/tools/symbol_tools.py` | Delete rows within a date range from a timeseries symbol, creating a new version. |
  126. | `get_symbol_info` | `arcticdb_mcp/tools/symbol_tools.py` | Return schema, row count, date range, and metadata summary for a symbol. |
  127. | `list_versions` | `arcticdb_mcp/tools/symbol_tools.py` | List all versions of a symbol with version number and write timestamp. |
  128. | `read_metadata` | `arcticdb_mcp/tools/symbol_tools.py` | Read only metadata for a symbol without loading its data. |
  129. | `write_metadata` | `arcticdb_mcp/tools/symbol_tools.py` | Update metadata for a symbol without modifying its data. |
  130. ### Batch Operations
  131. | Tool | File | What it does |
  132. |---|---|---|
  133. | `write_batch` | `arcticdb_mcp/tools/batch_tools.py` | Write multiple symbols in one call. |
  134. | `append_batch` | `arcticdb_mcp/tools/batch_tools.py` | Append to multiple symbols in one call. |
  135. | `update_batch` | `arcticdb_mcp/tools/batch_tools.py` | Update multiple symbols in one call. |
  136. | `delete_batch` | `arcticdb_mcp/tools/batch_tools.py` | Delete multiple symbols or symbol versions in one call. |
  137. | `read_batch` | `arcticdb_mcp/tools/batch_tools.py` | Read multiple symbols in one call. |
  138. | `read_metadata_batch` | `arcticdb_mcp/tools/batch_tools.py` | Read metadata for multiple symbols in one call. |
  139. | `get_description_batch` | `arcticdb_mcp/tools/batch_tools.py` | Get schema/description for multiple symbols in one call. |
  140. | `write_metadata_batch` | `arcticdb_mcp/tools/batch_tools.py` | Write metadata for multiple symbols in one call. |
  141. | `write_pickle` | `arcticdb_mcp/tools/batch_tools.py` | Write arbitrary pickle-serializable data to a symbol. |
  142. | `write_pickle_batch` | `arcticdb_mcp/tools/batch_tools.py` | Write multiple pickle-serializable payloads in one call. |
  143. ### Snapshots
  144. | Tool | File | What it does |
  145. |---|---|---|
  146. | `create_snapshot` | `arcticdb_mcp/tools/snapshot_tools.py` | Create a named snapshot of the current library state. |
  147. | `list_snapshots` | `arcticdb_mcp/tools/snapshot_tools.py` | List the names of all snapshots in a library. |
  148. | `delete_snapshot` | `arcticdb_mcp/tools/snapshot_tools.py` | Delete a named snapshot from a library. |
  149. | `read_symbol_from_snapshot` | `arcticdb_mcp/tools/snapshot_tools.py` | Read a symbol as it existed when a snapshot was created. |
  150. ### Query Helpers
  151. | Tool | File | What it does |
  152. |---|---|---|
  153. | `query_filter` | `arcticdb_mcp/tools/query_tools.py` | Filter rows using conditions. |
  154. | `query_filter_isin` | `arcticdb_mcp/tools/query_tools.py` | Filter rows where a column value is in a list. |
  155. | `query_groupby` | `arcticdb_mcp/tools/query_tools.py` | Group by a column and aggregate. |
  156. | `query_date_range` | `arcticdb_mcp/tools/query_tools.py` | Filter rows by date range on a datetime-indexed symbol. |
  157. | `query_resample` | `arcticdb_mcp/tools/query_tools.py` | Resample a datetime-indexed symbol and aggregate. |
  158. ### Maintenance
  159. | Tool | File | What it does |
  160. |---|---|---|
  161. | `reload_symbol_list` | `arcticdb_mcp/tools/maintenance_tools.py` | Force a symbol-list cache reload for a library. |
  162. | `compact_symbol_list` | `arcticdb_mcp/tools/maintenance_tools.py` | Compact symbol-list cache into a single key in storage. |
  163. | `is_symbol_fragmented` | `arcticdb_mcp/tools/maintenance_tools.py` | Check whether compaction would reduce segment count for a symbol. |
  164. | `defragment_symbol_data` | `arcticdb_mcp/tools/maintenance_tools.py` | Defragment symbol data by compacting fragmented row-sliced segments. |
  165. | `prune_previous_versions` | `arcticdb_mcp/tools/maintenance_tools.py` | Remove non-snapshotted symbol versions except the latest one. |
  166. ### Paginated Symbol Reads
  167. Use `read_symbol_page` to inspect large symbols a page at a time without loading the full dataset into memory or overflowing assistant response context:
  168. - **Parameters**: `library`, `symbol`, `offset` (default 0), `limit` (default 100, max 1000), optional `columns`, optional `as_of`.
  169. - **Backend Slicing**: Row ranges and column projections are pushed directly to ArcticDB storage engines.
  170. - **Version Pinning**: The initial page resolves the symbol's version (`version`). Pass `as_of=version` on subsequent pages to guarantee consistent reads across mutations.
  171. - **Continuation Info**: Each response includes `count`, `total_rows`, `has_more`, and `next_offset`.
  172. #### Two-Page Example
  173. ```python
  174. # Page 1: Read the first 100 rows of symbol AAPL
  175. page1 = read_symbol_page(library="finance", symbol="AAPL", offset=0, limit=100)
  176. # Returns: {"version": 2, "offset": 0, "limit": 100, "count": 100, "total_rows": 250, "has_more": True, "next_offset": 100, "data": [...]}
  177. # Page 2: Pin version=2 and use next_offset to fetch the next slice
  178. page2 = read_symbol_page(
  179. library="finance",
  180. symbol="AAPL",
  181. offset=page1["next_offset"],
  182. limit=100,
  183. as_of=page1["version"],
  184. )
  185. # Returns: {"version": 2, "offset": 100, "limit": 100, "count": 100, "total_rows": 250, "has_more": True, "next_offset": 200, "data": [...]}
  186. ```
  187. ## Example Prompts
  188. - "Read symbol NVDA from library finance"
  189. - "Filter NVDA where price > 500 and volume >= 1000"
  190. - "Resample ES_intraday to 5min and aggregate price mean, volume sum"
  191. - "Write metadata owner=research to symbol ES_intraday"
  192. - "Delete data in range for ES_intraday from 2024-01-01 to 2024-01-05"
  193. ## Development
  194. ```bash
  195. git clone https://github.com/YMuskrat/arcticdb-mcp
  196. cd arcticdb-mcp
  197. pip install -e .
  198. ```
  199. Run locally:
  200. ```bash
  201. ARCTICDB_URI=lmdb:///path/to/db python -m arcticdb_mcp
  202. ```
  203. Test with MCP Inspector:
  204. ```bash
  205. ARCTICDB_URI=lmdb:///tmp/test_db npx @modelcontextprotocol/inspector python -m arcticdb_mcp
  206. ```
  207. ## Community Backlog
  208. These ArcticDB capabilities are intentionally left open for contributors:
  209. - `stage`
  210. - `finalize_staged_data`
  211. - `sort_and_finalize_staged_data`
  212. - `delete_staged_data`
  213. - `get_staged_symbols`
  214. - `read_batch_and_join`
  215. - `admin_tools`
  216. ## Contributing
  217. See [CONTRIBUTING.md](CONTRIBUTING.md).
  218. ## License
  219. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.