# Claude Code Setup
This guide shows you how to use the MariaDB MCP Server with Claude Code (the VSCode extension).
## Quick Setup
### 1. Complete Initial Setup
First, run the setup script to create the virtual environment and install dependencies:
```bash
./setup.sh
```
### 2. Create `.mcp.json` Configuration
Create a `.mcp.json` file in the project root:
```bash
cp .mcp.example.json .mcp.json
```
Edit `.mcp.json` and update the paths and credentials:
```json
{
"mcpServers": {
"mariadb": {
"type": "stdio",
"command": "/absolute/path/to/mariadb_mcp_server/venv/bin/python",
"args": ["/absolute/path/to/mariadb_mcp_server/mariadb_mcp_server.py"],
"env": {
"MARIADB_HOST": "127.0.0.1",
"MARIADB_PORT": "3306",
"MARIADB_USER": "root",
"MARIADB_PASSWORD": "your_password",
"MARIADB_DATABASE": "your_database",
"MARIADB_READ_ONLY": "false",
"MARIADB_POOL_SIZE": "5"
}
}
}
}
```
### 3. Reload Claude Code
Press `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux) and run:
- **"Developer: Reload Window"**
Or use the command:
```bash
claude mcp reload
```
### 4. Verify Installation
You can verify the MCP server is loaded by asking Claude:
- "What MCP tools do you have available?"
- "List the available databases"
## Using Environment Variables (Recommended)
Instead of hardcoding credentials in `.mcp.json`, you can use environment variables:
```json
{
"mcpServers": {
"mariadb": {
"type": "stdio",
"command": "/absolute/path/to/venv/bin/python",
"args": ["/absolute/path/to/mariadb_mcp_server.py"],
"env": {
"MARIADB_HOST": "${MARIADB_HOST:-127.0.0.1}",
"MARIADB_PORT": "${MARIADB_PORT:-3306}",
"MARIADB_USER": "${MARIADB_USER:-root}",
"MARIADB_PASSWORD": "${MARIADB_PASSWORD}",
"MARIADB_DATABASE": "${MARIADB_DATABASE:-}",
"MARIADB_READ_ONLY": "${MARIADB_READ_ONLY:-false}",
"MARIADB_POOL_SIZE": "${MARIADB_POOL_SIZE:-5}"
}
}
}
}
```
Then set environment variables before launching VSCode:
```bash
export MARIADB_PASSWORD="your_password"
export MARIADB_DATABASE="your_database"
code .
```
## CLI Management
You can also manage MCP servers using the Claude Code CLI:
### Add Server
```bash
claude mcp add --transport stdio mariadb -- /path/to/venv/bin/python /path/to/mariadb_mcp_server.py
```
### List Servers
```bash
claude mcp list
```
### Remove Server
```bash
claude mcp remove mariadb
```
### Reload Configuration
```bash
claude mcp reload
```
## Project vs User Scope
### Project Scope (Recommended for Teams)
Store `.mcp.json` in your project root (this is what we've done):
- ✓ Version controlled (use `.mcp.example.json`)
- ✓ Shared with team
- ✓ Project-specific settings
### User Scope (Personal Use)
Install globally for all projects:
```bash
claude mcp add --scope user --transport stdio mariadb -- /path/to/venv/bin/python /path/to/mariadb_mcp_server.py
```
## Example Usage
Once configured, you can ask Claude in the IDE:
```
You: "What tables are in the hems database?"
Claude: [Uses list_tables tool]
You: "Show me the schema for the transformers table"
Claude: [Uses get_table_schema tool]
You: "Find all transformers with power > 100kW"
Claude: [Uses execute_query tool]
```
## Troubleshooting
### MCP Server Not Loading
1. Check the logs in Claude Code Developer Console:
- `Cmd+Shift+P` → "Developer: Toggle Developer Tools"
- Look for MCP-related errors
2. Verify paths are absolute:
```bash
# Get absolute path
echo "$(pwd)/venv/bin/python"
```
3. Test the server manually:
```bash
export MARIADB_HOST=127.0.0.1
export MARIADB_PASSWORD=your_password
venv/bin/python mariadb_mcp_server.py
```
### "spawn ENOENT" Error
- Make sure you're using absolute paths in `.mcp.json`
- Verify the Python executable exists:
```bash
ls -la /path/to/venv/bin/python
```
### Connection Errors
- Use `127.0.0.1` instead of `localhost` to force TCP
- Verify MariaDB is running:
```bash
mysql -h 127.0.0.1 -u root -p
```
## Security Best Practices
1. **Never commit `.mcp.json`** with real credentials
- It's already in `.gitignore`
- Use `.mcp.example.json` as a template
2. **Use environment variables** for sensitive data
3. **Enable read-only mode** unless you need write access:
```json
"MARIADB_READ_ONLY": "true"
```
4. **Create dedicated database users** with minimal permissions:
```sql
CREATE USER 'claude_readonly'@'localhost' IDENTIFIED BY 'password';
GRANT SELECT ON your_database.* TO 'claude_readonly'@'localhost';
```
## Differences from Claude Desktop
| Feature | Claude Desktop | Claude Code |
|---------|---------------|-------------|
| Config File | `~/Library/.../claude_desktop_config.json` | `.mcp.json` in project |
| Scope | User-wide | Project-specific |
| Version Control | Not shared | Can be shared (template) |
| Environment Variables | Basic support | Full `${VAR}` expansion |
| Management | Manual editing | CLI + manual editing |
## Next Steps
- Read the main [README.md](README.md) for full documentation
- Check [QUICK_START.md](QUICK_START.md) for general setup
- Review [config_examples.md](config_examples.md) for more configurations
## Getting Help
If you encounter issues:
1. Check the Developer Console in Claude Code
2. Verify your database connection manually
3. Review this troubleshooting section
4. Open an issue on GitHub with error details
