mirror of
https://github.com/executeautomation/mcp-database-server.git
synced 2025-12-09 21:12:57 +08:00
Enhance README with usage options and configuration details for MCP Database Server. Added sections for direct usage, local development setup, and available database tools, along with practical examples and additional documentation links.
This commit is contained in:
Karthik KK
185
docs/usage-examples.md
Normal file
185
docs/usage-examples.md
Normal file
@@ -0,0 +1,185 @@
|
||||
# MCP Database Server Usage Examples
|
||||
|
||||
This document provides practical examples of how to use the database tools provided by the MCP Database Server with Claude Desktop.
|
||||
|
||||
## Example Prompts for Claude
|
||||
|
||||
Here are examples of tasks you can ask Claude to perform using the MCP Database Server tools.
|
||||
|
||||
### Basic Database Operations
|
||||
|
||||
#### Listing Tables
|
||||
|
||||
```
|
||||
What tables are in the database?
|
||||
```
|
||||
|
||||
#### Describing a Table
|
||||
|
||||
```
|
||||
Show me the structure of the Products table.
|
||||
```
|
||||
|
||||
#### Reading Data
|
||||
|
||||
```
|
||||
Show me all records from the Customers table.
|
||||
```
|
||||
|
||||
```
|
||||
Find all products with a price greater than 50.
|
||||
```
|
||||
|
||||
#### Writing Data
|
||||
|
||||
```
|
||||
Insert a new product with the name "New Widget", price 29.99, and category "Accessories".
|
||||
```
|
||||
|
||||
```
|
||||
Update the price of all products in the "Electronics" category to increase by 10%.
|
||||
```
|
||||
|
||||
```
|
||||
Delete all orders that are more than 5 years old.
|
||||
```
|
||||
|
||||
### Schema Management
|
||||
|
||||
#### Creating a Table
|
||||
|
||||
```
|
||||
Create a new table called "Feedback" with columns for ID (auto-increment primary key),
|
||||
CustomerID (integer), Rating (integer 1-5), and Comment (text).
|
||||
```
|
||||
|
||||
#### Altering a Table
|
||||
|
||||
```
|
||||
Add a "DateCreated" datetime column to the Products table.
|
||||
```
|
||||
|
||||
```
|
||||
Rename the "Phone" column in the Customers table to "ContactNumber".
|
||||
```
|
||||
|
||||
#### Dropping a Table
|
||||
|
||||
```
|
||||
Delete the temporary_logs table if it exists.
|
||||
```
|
||||
|
||||
### Advanced Queries
|
||||
|
||||
#### Complex Joins
|
||||
|
||||
```
|
||||
Show me a list of customers along with their total order amounts,
|
||||
sorted from highest to lowest total amount.
|
||||
```
|
||||
|
||||
#### Exporting Data
|
||||
|
||||
```
|
||||
Export all customer data as CSV.
|
||||
```
|
||||
|
||||
```
|
||||
Export the sales summary by month as JSON.
|
||||
```
|
||||
|
||||
## SQL Syntax Examples
|
||||
|
||||
### SQLite Examples
|
||||
|
||||
```sql
|
||||
-- Creating a table in SQLite
|
||||
CREATE TABLE Products (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
name TEXT NOT NULL,
|
||||
price REAL,
|
||||
category TEXT
|
||||
);
|
||||
|
||||
-- Querying with LIMIT and OFFSET
|
||||
SELECT * FROM Products LIMIT 10 OFFSET 20;
|
||||
|
||||
-- Date formatting
|
||||
SELECT date('now') as today;
|
||||
SELECT strftime('%Y-%m-%d', date_column) as formatted_date FROM Orders;
|
||||
|
||||
-- String concatenation
|
||||
SELECT first_name || ' ' || last_name as full_name FROM Customers;
|
||||
```
|
||||
|
||||
### SQL Server Examples
|
||||
|
||||
```sql
|
||||
-- Creating a table in SQL Server
|
||||
CREATE TABLE Products (
|
||||
id INT IDENTITY(1,1) PRIMARY KEY,
|
||||
name NVARCHAR(100) NOT NULL,
|
||||
price DECIMAL(10,2),
|
||||
category NVARCHAR(50)
|
||||
);
|
||||
|
||||
-- Querying with OFFSET-FETCH (SQL Server equivalent of LIMIT)
|
||||
SELECT * FROM Products ORDER BY id OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY;
|
||||
|
||||
-- Date formatting
|
||||
SELECT FORMAT(GETDATE(), 'yyyy-MM-dd') as today;
|
||||
SELECT CONVERT(VARCHAR(10), date_column, 120) as formatted_date FROM Orders;
|
||||
|
||||
-- String concatenation
|
||||
SELECT first_name + ' ' + last_name as full_name FROM Customers;
|
||||
```
|
||||
|
||||
## Working with Claude
|
||||
|
||||
### Tips for Using the MCP Database Server
|
||||
|
||||
1. **Be specific about database type**: If you have both SQLite and SQL Server configurations, tell Claude which one you want to use.
|
||||
|
||||
2. **Security awareness**: Avoid exposing sensitive database credentials in your conversations.
|
||||
|
||||
3. **SQL syntax differences**: Remember that SQL syntax might differ between SQLite and SQL Server.
|
||||
|
||||
4. **Error handling**: If Claude encounters an error, it will tell you what went wrong so you can correct your query.
|
||||
|
||||
5. **Complex operations**: For complex operations, consider breaking them down into smaller steps.
|
||||
|
||||
### Example Claude Conversations
|
||||
|
||||
#### Exploring a Database
|
||||
|
||||
**User**: "I need to explore my database. What tables do I have?"
|
||||
|
||||
**Claude**: *Uses list_tables to show available tables*
|
||||
|
||||
**User**: "Tell me about the Customers table structure."
|
||||
|
||||
**Claude**: *Uses describe_table to show the schema of the Customers table*
|
||||
|
||||
**User**: "Show me the first 5 records from the Customers table."
|
||||
|
||||
**Claude**: *Uses read_query to execute a SELECT query*
|
||||
|
||||
#### Data Analysis
|
||||
|
||||
**User**: "Find customers who haven't placed an order in the last 6 months."
|
||||
|
||||
**Claude**: *Uses read_query with a more complex query involving dates and joins*
|
||||
|
||||
**User**: "Create a summary of sales by product category."
|
||||
|
||||
**Claude**: *Uses read_query with GROUP BY to aggregate sales data*
|
||||
|
||||
#### Database Modifications
|
||||
|
||||
**User**: "I need to add an 'active' column to the Users table with a default value of true."
|
||||
|
||||
**Claude**: *Uses alter_table to modify the schema*
|
||||
|
||||
**User**: "Update all products in the 'Discontinued' category to set their 'active' status to false."
|
||||
|
||||
**Claude**: *Uses write_query to perform an UPDATE operation*
|
||||
107
readme.md
107
readme.md
@@ -20,6 +20,30 @@ npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Usage Options
|
||||
|
||||
There are two ways to use this MCP server with Claude:
|
||||
|
||||
1. **Direct usage**: Install the package globally and use it directly
|
||||
2. **Local development**: Run from your local development environment
|
||||
|
||||
### Direct Usage with NPM Package
|
||||
|
||||
The easiest way to use this MCP server is by installing it globally:
|
||||
|
||||
```bash
|
||||
npm install -g @executeautomation/database-server
|
||||
```
|
||||
|
||||
This allows you to use the server directly without building it locally.
|
||||
|
||||
### Local Development Setup
|
||||
|
||||
If you want to modify the code or run from your local environment:
|
||||
|
||||
1. Clone and build the repository as shown in the Installation section
|
||||
2. Run the server using the commands in the Usage section below
|
||||
|
||||
## Usage
|
||||
|
||||
### SQLite Database
|
||||
@@ -47,24 +71,28 @@ Optional parameters:
|
||||
- `--password`: Password for SQL Server authentication
|
||||
- `--port`: Port number (default: 1433)
|
||||
|
||||
## Configuring Claude
|
||||
## Configuring Claude Desktop
|
||||
|
||||
Update your Claude configuration file to add the MCP Database Server:
|
||||
### Direct Usage Configuration
|
||||
|
||||
If you installed the package globally, configure Claude Desktop with:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"sqlite": {
|
||||
"command": "node",
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"/path/to/mcp-database-server/dist/src/index.js",
|
||||
"-y",
|
||||
"@executeautomation/database-server",
|
||||
"/path/to/your/database.db"
|
||||
]
|
||||
},
|
||||
"sqlserver": {
|
||||
"command": "node",
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"/path/to/mcp-database-server/dist/src/index.js",
|
||||
"-y",
|
||||
"@executeautomation/database-server",
|
||||
"--sqlserver",
|
||||
"--server", "your-server-name",
|
||||
"--database", "your-database-name",
|
||||
@@ -76,20 +104,63 @@ Update your Claude configuration file to add the MCP Database Server:
|
||||
}
|
||||
```
|
||||
|
||||
## Available Tools
|
||||
### Local Development Configuration
|
||||
|
||||
The MCP Database Server provides the following tools:
|
||||
For local development, configure Claude Desktop to use your locally built version:
|
||||
|
||||
- `read_query`: Execute SELECT queries to read data from the database
|
||||
- `write_query`: Execute INSERT, UPDATE, or DELETE queries
|
||||
- `create_table`: Create new tables in the database
|
||||
- `alter_table`: Modify existing table schema (add columns, rename tables, etc.)
|
||||
- `drop_table`: Remove a table from the database with safety confirmation
|
||||
- `export_query`: Export query results to various formats (CSV, JSON)
|
||||
- `list_tables`: Get a list of all tables in the database
|
||||
- `describe_table`: View schema information for a specific table
|
||||
- `append_insight`: Add a business insight to the memo
|
||||
- `list_insights`: List all business insights in the memo
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"sqlite": {
|
||||
"command": "node",
|
||||
"args": [
|
||||
"/absolute/path/to/mcp-database-server/dist/src/index.js",
|
||||
"/path/to/your/database.db"
|
||||
]
|
||||
},
|
||||
"sqlserver": {
|
||||
"command": "node",
|
||||
"args": [
|
||||
"/absolute/path/to/mcp-database-server/dist/src/index.js",
|
||||
"--sqlserver",
|
||||
"--server", "your-server-name",
|
||||
"--database", "your-database-name",
|
||||
"--user", "your-username",
|
||||
"--password", "your-password"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The Claude Desktop configuration file is typically located at:
|
||||
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
- Linux: `~/.config/Claude/claude_desktop_config.json`
|
||||
|
||||
## Available Database Tools
|
||||
|
||||
The MCP Database Server provides the following tools that Claude can use:
|
||||
|
||||
| Tool | Description | Required Parameters |
|
||||
|------|-------------|---------------------|
|
||||
| `read_query` | Execute SELECT queries to read data | `query`: SQL SELECT statement |
|
||||
| `write_query` | Execute INSERT, UPDATE, or DELETE queries | `query`: SQL modification statement |
|
||||
| `create_table` | Create new tables in the database | `query`: CREATE TABLE statement |
|
||||
| `alter_table` | Modify existing table schema | `query`: ALTER TABLE statement |
|
||||
| `drop_table` | Remove a table from the database | `table_name`: Name of table<br>`confirm`: Safety flag (must be true) |
|
||||
| `list_tables` | Get a list of all tables | None |
|
||||
| `describe_table` | View schema information for a table | `table_name`: Name of table |
|
||||
| `export_query` | Export query results as CSV/JSON | `query`: SQL SELECT statement<br>`format`: "csv" or "json" |
|
||||
| `append_insight` | Add a business insight to memo | `insight`: Text of insight |
|
||||
| `list_insights` | List all business insights | None |
|
||||
|
||||
For practical examples of how to use these tools with Claude, see [Usage Examples](docs/usage-examples.md).
|
||||
|
||||
## Additional Documentation
|
||||
|
||||
- [SQL Server Setup Guide](docs/sql-server-setup.md): Details on connecting to SQL Server databases
|
||||
- [Usage Examples](docs/usage-examples.md): Example queries and commands to use with Claude
|
||||
|
||||
## Development
|
||||
|
||||
|
||||
Reference in New Issue
Block a user