# 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:
```bash
npm install
```
3. Create your configuration file:
```bash
cp config.example.json config.json
```
4. Edit `config.json` with your database credentials:
```json
{
"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:
```bash
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`
```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:
```bash
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:
```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
