Boxtalk Data MCP Server

A Model Context Protocol (MCP) server that provides SQL Server database operations with pagination, table structure inspection, and record counting capabilities.

Features

• Get Table Data: Retrieve paginated data from any SQL Server table
• Get Record Count: Get the total number of records in a table
• Get Table Structure: View table schema including columns, data types, primary keys, and foreign keys
• Configurable Connection: Easy database configuration via JSON file
• Enforced Pagination: Prevents large data dumps with configurable page sizes (max 1000 records per page)

Prerequisites

• Node.js (v16 or higher)
• SQL Server database (local or remote)
• Database credentials with read access

Installation

1. Clone or navigate to this directory

2. Install dependencies:

npm install

3. Create your configuration file:

cp config.example.json config.json

4. Edit config.json with your database credentials:

{
  "database": {
    "user": "your_username",
    "password": "your_password",
    "server": "localhost",
    "database": "your_database_name",
    "options": {
      "encrypt": true,
      "trustServerCertificate": false,
      "enableArithAbort": true
    },
    "pool": {
      "max": 10,
      "min": 0,
      "idleTimeoutMillis": 30000
    }
  }
}

Configuration Options

• user: SQL Server username
• password: SQL Server password
• server: SQL Server hostname or IP address
• database: Database name
• options.encrypt: Enable encryption (recommended for production)
• options.trustServerCertificate: Set to true for local development with self-signed certificates
• pool.max: Maximum number of connections in the pool
• pool.min: Minimum number of connections in the pool
• pool.idleTimeoutMillis: Time before idle connections are closed

Alternative Configuration

You can also specify a custom configuration file path using the DB_CONFIG_PATH environment variable:

DB_CONFIG_PATH=/path/to/custom/config.json node index.js

Usage with Claude Desktop

To use this MCP server with Claude Desktop, add it to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "boxtalk-data": {
      "command": "node",
      "args": ["/path/to/boxtalk-data-mcp/index.js"],
      "env": {
        "DB_CONFIG_PATH": "/path/to/boxtalk-data-mcp/config.json"
      }
    }
  }
}

After adding the configuration, restart Claude Desktop.

Available Tools

1. get_table_data

Retrieve paginated data from a SQL Server table.

Parameters:

• table (required): Table name (e.g., "Users" or "dbo.Users")
• page (optional): Page number, defaults to 1
• pageSize (optional): Records per page (1-1000), defaults to 100
• orderBy (optional): Column to order by, defaults to first column

Example:

Get the first 50 records from the Users table, ordered by UserId

2. get_table_count

Get the total count of records in a table.

Parameters:

• table (required): Table name (e.g., "Users" or "dbo.Users")

Example:

How many records are in the Orders table?

3. get_table_structure

Get the structure/schema of a table including columns, data types, and constraints.

Parameters:

• table (required): Table name (e.g., "Users" or "dbo.Users")

Example:

Show me the structure of the Products table

Testing

You can test the server using the MCP inspector:

npm install -g @modelcontextprotocol/inspector
mcp-inspector node index.js

Security Considerations

• Never commit config.json to version control
• Use strong database passwords
• Grant only necessary permissions to the database user
• Enable encryption for production environments
• Consider using environment variables for sensitive credentials

Troubleshooting

Connection Errors

If you encounter connection errors:

1. Verify SQL Server is running and accessible
2. Check firewall settings allow connection on SQL Server port (default 1433)
3. Confirm credentials are correct
4. For local development with self-signed certificates, set trustServerCertificate: true

Authentication Issues

For Windows Authentication, modify config.json:

{
  "database": {
    "server": "localhost",
    "database": "your_database_name",
    "options": {
      "trustedConnection": true,
      "encrypt": true,
      "trustServerCertificate": true
    }
  }
}

Table Not Found

Ensure you specify the correct schema (e.g., "dbo.TableName" instead of just "TableName").

License

MIT