home / mcp / cosmos db mcp server

Cosmos DB MCP Server

This read-only MCP Server allows you to connect to Cosmos DB data from Claude Desktop through CData JDBC Drivers. For full CRUD support, check out the first managed MCP platform: CData Connect AI (https://www.cdata.com/ai/).

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "cdatasoftware-cosmos-db-mcp-server-by-cdata": {
      "command": "java",
      "args": [
        "-jar",
        "CDataMCP-jar-with-dependencies.jar",
        "/PATH/TO/cosmos-db.prp"
      ]
    }
  }
}

You run a local, read-only MCP server that exposes Cosmos DB data through a simple MCP interface. This enables you to query live Cosmos DB data using natural language or an MCP client, without writing SQL. The server relies on the CData JDBC Driver for Cosmos DB to translate Cosmos DB data into relational-like access.

How to use

Once the MCP server is configured and running, you connect an MCP client to it. The server provides three core capabilities you can leverage through your client tools: list available tables, list columns for a table, and run read queries. You do not need to write SQL to ask questions; you simply request data in natural language or use the built-in tools from your MCP client to discover schema and retrieve results. Typical usage patterns involve asking questions like which accounts exist in a table, what columns are available for a particular dataset, or retrieving all records that meet a condition. The client will route these requests to the MCP server, which executes against Cosmos DB via the CData JDBC Driver and returns results in a consumable format.

Key tool names you will interact with (when composing requests) include {servername}_get_tables, {servername}_get_columns, and {servername}_run_query. The server returns results in CSV-like form for table and column introspections, and standard result rows for queries.

How to install

Prerequisites: you need a Java Runtime Environment and Maven for building the server locally.

# 1) Clone the MCP server repository
git clone https://github.com/cdatasoftware/cosmos-db-mcp-server-by-cdata.git
cd cosmos-db-mCP-server-by-cdata

# 2) Build the server JAR with dependencies
mvn clean install

# This creates the JAR file: CDataMCP-jar-with-dependencies.jar

3) Install the CData JDBC Driver for Cosmos DB (required for the MCP server to talk to Cosmos DB). Follow the driver's installation instructions and license steps provided by the vendor. Then license the driver as shown in the steps below.

# License the CData JDBC Driver (example path may vary by OS)
java -jar cdata.jdbc.cosmosdb.jar --license
# Enter your name, email, and your license key when prompted

4) Create a JDBC connection string using the driver's connection utility and test the connection. Copy the resulting JDBC URL for use in your property file.

# Open the connection string utility (example)
java -jar cdata.jdbc.cosmosdb.jar
# Configure your connection and test it. Copy the connection string when successful

5) Create a properties file for the MCP server connection (for example cosmos-db.prp) with the required fields. Include the JDBC URL you copied earlier and specify the driver class and path.

Prefix=cosmosdb
ServerName=CDataCosmosDB
ServerVersion=1.0
DriverPath=PATH\TO\cdata.jdbc.cosmosdb.jar
DriverClass=cdata.jdbc.cosmosdb.CosmosDBDriver
JdbcUrl=jdbc:cosmosdb:InitiateOAuth=GETANDREFRESH;
Tables=

Additional setup for Claude Desktop or similar clients

If you are configuring Claude Desktop or another MCP client to use this server, add an MCP entry that runs the MCP server using your cosmos-db.prp file.

{
  "mcpServers": {
    "cosmosdb_mcp": {
      "command": "PATH\\TO\\java.exe",
      "args": [
        "-jar",
        "PATH\\TO\\CDataMCP-jar-with-dependencies.jar",
        "PATH\\TO\\cosmos-db.prp"
      ]
    }
  }
}

Running the server now

Start the MCP server on its own using the Java JAR and your properties file. The server operates over stdio, so it is intended to be used with a local client on the same machine.

java -jar /PATH/TO/CDataMCP-jar-with-dependencies.jar /PATH/TO/cosmos-db.prp

Notes on usage and capabilities

Once running, you can interact with Cosmos DB data through built-in tools exposed by the MCP server. You can list available tables, inspect columns, and run read queries. Examples of questions you can ask include asking for correlations across datasets, counts of specific records, or summaries of data by category.

For example, you can ask about data relationships such as which accounts match a particular criterion, how many items meet a condition, or what events are scheduled for today. The server translates these requests into SQL-like queries under the hood via the CData JDBC Driver and returns the results to your MCP client.

Troubleshooting

If the MCP server does not appear in your client, ensure you have fully quit and restarted the client after starting the server. Verify that the cosmos-db.prp file contains the correct JDBC URL and driver information. If you run into connection issues, re-create the JDBC connection string using the driver’s utility and re-test the connection.

If you encounter issues with the MCP server itself or have feedback, reach out to the CData Community or support channels for Cosmos DB. The project is distributed under MIT and license terms apply for the JDBC driver.

License

This MCP server is released under the MIT License. You may use, modify, and distribute it in accordance with the MIT terms.

All supported sources

Cosmos DB is supported through the CData JDBC Driver, which exposes Cosmos DB data as relational models that the MCP server can access.

Available tools

cosmosdb_get_tables

Retrieves a list of tables available in the Cosmos DB data source. The output is CSV with column headers in the first line.

cosmosdb_get_columns

Retrieves a list of columns for a specified table. The output is CSV with column headers in the first line.

cosmosdb_run_query

Executes a SQL SELECT query against the Cosmos DB data exposed through the MCP server.