Steampipe MCP Server

An MCP server interacting with PostgreSQL databases, primarily for use with Steampipe.

Steampipe has a schema per connection, and creates a search_path that includes all the schemas, but public schema is typically empty. In additiona to that, Steampipe plugins for AWS, GCP and other clouds have a lot of tables, so just listing all of them is not practical. So, the recommended way to prompt your Claude Desktop would be to say something like this: "In steampipe using aws_all schema, give me a list of all ec2 instances". This way Claude will be more likely to use list_tables_in_schema in schema command, to limit the number of tables retrieved.

Prerequisites

1. Install Steampipe

macOS:

brew tap turbot/tap
brew install steampipe

Linux:

sudo /bin/sh -c "$(curl -fsSL https://steampipe.io/install/steampipe.sh)"

Windows:

iwr -useb https://steampipe.io/install/steampipe.ps1 | iex

2. Start Steampipe Service

Start Steampipe as a background service:

steampipe service start

You can verify the service is running with:

steampipe service status

3. Get Database URL

The Steampipe PostgreSQL connection string can be found:

steampipe service status

Look for the Database URL in the output, which typically looks like:

postgres://steampipe:password@localhost:9193/steampipe

You can provide this URL in the --database-url argument when running the server:

steampipe-mcp --database-url postgresql://steampipe:password@localhost:9193/steampipe

Note: Protocol must be postgresql:// for the server to work correctly.

4. Configuring Environment Variables

You can configure the database connection using an environment variable instead of passing it each time:

1. Create a .env file in the project directory with your database URL:

   DATABASE_URL=postgresql://steampipe:password@localhost:9193/steampipe
   

2. The server will automatically load this configuration when starting up.

Available Tools

This MCP server provides several useful tools for interacting with your PostgreSQL database:

query

Runs a read-only SQL query against the database and returns results as JSON.

list_all_tables

Lists all available tables in all schemas in your database's search path. Steampipe doesn't use public schema, there is schema per connection.

list_tables_in_schema

Lists all tables within a specific schema. Useful to limit the amount of tables, especially when working with just one schema.

get_table_schema

Retrieves column names and data types for a specific table, table should be in a format like schema.table.

Project Structure

steampipe-mcp-server/
├── src/
│   └── steampipe_mcp_server/  # Main package
│       ├── __init__.py
│       ├── cli.py             # Command-line interface
│       ├── database.py        # Database service
│       ├── server.py          # MCP server setup
│       ├── tools.py           # MCP tools implementation
│       └── test_utils.py      # Testing utilities
├── tests/                     # Test directory
├── Makefile                   # Build automation
├── pyproject.toml             # Project configuration
└── README.md                  # This file

Installation

Development Setup (Recommended)

The easiest way to get started is to use the included Makefile:

# Create a virtual environment first
uv venv

# Install development dependencies
make dev-install

# View all available commands
make help

Alternatively, you can:

1. Clone the repository
2. Create a virtual environment: uv venv
3. Activate the environment: source .venv/bin/activate (Linux/macOS) or .venv\Scripts\activate (Windows)
4. Install dev dependencies: uv pip install -e .[dev]

Install from Source

pip install -e .

Development

Using the Makefile

The project includes a Makefile with common tasks:

# Run the server in development mode with Inspector
make dev

# Run tests
make test

# Run linting
make lint

# Run type checking
make typecheck

# Format code
make format

# Run all checks (lint and typecheck)
make check

# Install in Claude Desktop
make install-mcp

Run make help to see all available commands.

How to Run

1. Development Mode (Recommended)

# Using make
make dev

# OR manually
mcp dev src/steampipe_mcp_server/cli.py

This will start the server and the MCP Inspector, allowing you to test the query tool and other tools interactively.

2. Using CLI

After installation:

# Using make
make server

# OR with explicit URL
steampipe-mcp --database-url postgresql://steampipe:password@localhost:9193/steampipe

# OR with environment variable
export DATABASE_URL=postgresql://steampipe:password@localhost:9193/steampipe
steampipe-mcp

3. Install in Claude Desktop

Development Version

For development and testing:

# Using make (ensure DATABASE_URL environment variable is set)
make install-mcp

# OR manually
mcp install steampipe_mcp_server.cli:main

Published Version

For the published version, you can configure Claude Desktop directly:

1. Open Claude Desktop
2. Navigate to Settings > Developer > Edit Config
3. Add the following configuration to the JSON file:

{
  "mcpServers": {
    "steampipe": {
      "command": "uvx",
      "args": [
        "steampipe-mcp-server",
        "--database-url",
        "postgresql://steampipe:password@localhost:9193/steampipe"
      ]
    }
  }
}

4. Save the config file and restart Claude Desktop

Replace the database URL with your actual Steampipe database URL. This configuration uses uvx to execute the published package directly.

The tools will be available within Claude under the steampipe namespace.

Testing

Run tests with:

# Using make
make test

# OR manually
pytest

For tests that require a database connection, set the TEST_DB_URL environment variable.

Contributing

1. Fork the repository
2. Create a new branch for your feature
3. Make your changes
4. Run tests and checks: make check test
5. Submit a pull request