Argos-MCP v3.0.1 <!-- x-release-please-version -->

Argos Panoptes — the hundred-eyed giant who never slept, set to watch over what mattered most.

Argos-MCP — a hundred eyes on your databases. Connect Claude Code to PostgreSQL, MySQL, SQLite, and SQL Server with bulletproof security, comprehensive monitoring, and seamless multi-database support.

Why Argos-MCP?

Security First

• SELECT-Only Mode - Production-safe read-only database access
• Query Validation - Advanced SQL injection prevention and complexity analysis
• SSH Tunneling - Secure encrypted connections through bastion hosts
• Audit Logging - Comprehensive security event tracking

High Performance

• Connection Pooling - Efficient database connection management
• Schema Caching - Lightning-fast metadata access
• Query Optimization - Built-in performance analysis and recommendations
• Batch Operations - Execute multiple queries with transaction support

Universal Database Support

• PostgreSQL - Full support including advanced features
• MySQL/MariaDB - Complete compatibility with all versions
• SQLite - Perfect for development and small applications
• SQL Server - Enterprise-grade Microsoft SQL Server support

Developer Experience

• One-command install - Registers with Claude Code via the native claude mcp add
• TypeScript Native - Full type safety and IntelliSense support
• Comprehensive Docs - Detailed guides, tutorials, and API reference
• Extensive Testing - Unit, integration, and end-to-end test coverage

Quick Start

Requirements: Node.js >= 22 and the Claude Code CLI.

1. Build

git clone https://github.com/AraneaDev/Argos-MCP.git
cd Argos-MCP
npm install
npm run build

2. Configure databases

npm run setup

Interactive wizard for adding database connections, security settings, and SSH tunnels. It writes a config.ini — by convention at ~/.config/argos/config.ini, though any path works. You can also add databases at runtime with the sql_add_database tool.

3. Register with Claude Code

claude mcp add argos --scope user -- \
  node "$(pwd)/dist/index.js" --config "$HOME/.config/argos/config.ini"

Scopes:

Scope	Flag	Where it lives	Use when
User	--scope user	~/.claude.json	You want Argos in every project (most common)
Project	--scope project	.mcp.json in the repo	You want to share it with your team via git
Local	(default)	Per-project, private	You're just trying it out

4. Verify

claude mcp list

You should see argos listed as connected. Its tools appear in Claude Code as mcp__argos__sql_query, mcp__argos__sql_get_schema, and so on.

Removing it

claude mcp remove argos --scope user

Use Cases

Data Analytics & Business Intelligence

"Show me the top 10 customers by revenue this quarter, including their growth rate compared to last quarter"

Production Database Monitoring

"Check the status of our user registration system - how many signups in the last 24 hours and any error patterns?"

Database Administration

"Analyze the performance of our product catalog queries and suggest optimizations"

Development & Testing

"Generate test data scenarios based on our current user demographics"

Architecture

graph TB
 Claude[Claude Code] --> MCP[MCP Protocol]
 MCP --> Security[Security Layer]
 Security --> Connection[Connection Manager]
 Connection --> Adapters[Database Adapters]

 Adapters --> PostgreSQL[(PostgreSQL)]
 Adapters --> MySQL[(MySQL)]
 Adapters --> SQLite[(SQLite)]
 Adapters --> MSSQL[(SQL Server)]

 Security --> SSH[SSH Tunneling]
 SSH --> Bastion[Bastion Host]
 Bastion --> RemoteDB[(Remote Database)]

Built on solid foundations:

• TypeScript - Full type safety and modern development experience
• Node.js - Cross-platform compatibility and excellent ecosystem
• MCP Protocol - Standard protocol for AI tool integration
• Industry-standard drivers - Proven database connectivity libraries

Documentation Hub

Getting Started

• 5-Minute Quick Start - Get running fast
• Installation Guide - Detailed setup instructions
• First Database Tutorial - Connect your first database
• Claude Integration - Register with Claude Code

Architecture & Design

• System Architecture - How it all works together
• Security Architecture - Defense-in-depth security model
• Database Layer - Adapter pattern implementation

API Reference

• MCP Tools Reference - Complete tool documentation
• TypeScript API - Developer API reference
• Configuration Reference - All configuration options

Advanced Guides

• Multi-Database Setup - Managing multiple databases
• SSH Tunneling - Secure remote access
• Security Hardening - Production security guide
• Performance Tuning - Optimization strategies

Browse All Documentation

Configuration Examples

Production PostgreSQL with SSH

[database.production]
type=postgresql
host=internal-db.company.local
port=5432
database=production_app
username=readonly_user
password=secure_random_password
ssl=true
select_only=true
timeout=15000

# SSH Tunnel Configuration
ssh_host=bastion.company.com
ssh_port=22
ssh_username=tunnel_user
ssh_private_key=/secure/path/ssh_key

[security]
max_joins=5
max_subqueries=3
max_complexity_score=50

Multi-Database Analytics Setup

[database.transactions]
type=postgresql
host=transactions-db.company.com
database=transactions
select_only=true

[database.users]
type=mysql
host=users-db.company.com
database=users
select_only=true

[database.analytics]
type=sqlite
file=./data/analytics.sqlite
select_only=false

[database.local_cache]
type=sqlite
file=./data/cache.sqlite
select_only=false
mcp_configurable=true

[extension]
max_rows=1000
query_timeout=30000

Security Features

Multi-Layer Security Model

1. Query Validation - SQL injection prevention and syntax analysis
2. Complexity Limits - Prevent resource-intensive queries
3. SELECT-Only Mode - Read-only database access for production safety
4. Connection Encryption - SSL/TLS and SSH tunnel support
5. Audit Logging - Comprehensive security event tracking
6. Field Redaction - Automatic masking of sensitive data in query results

Field Redaction

Automatically mask, replace, or partially obscure sensitive fields (emails, phone numbers, SSNs, etc.) in query results before they reach Claude or other clients. Redaction is configured per-database in config.ini:

[database.production]
type=postgresql
host=prod-db.company.com
database=app_db
username=readonly_user
password=secure_pass
select_only=true

# Field Redaction
redaction_enabled=true
redaction_rules=*email*:partial_mask,*phone*:full_mask,ssn:replace:[PROTECTED]
redaction_case_sensitive=false
redaction_log_access=true

Redaction types:

Type	Example Input	Example Output
partial_mask	john.doe@example.com	j******.e@*****.com
full_mask	555-123-4567	************
replace	123-45-6789	[PROTECTED]
custom	Regex-based	Custom pattern

Field patterns: exact match (email), wildcard (*email*), or regex (/^user_.+$/).

Full Redaction Guide

Enterprise Security Compliance

• SOC 2 Type II compatible logging and monitoring
• GDPR/CCPA compliant data access controls
• HIPAA suitable with proper configuration
• PCI DSS compatible for payment data environments

Dynamic Database Management

Argos-MCP supports runtime database management through dedicated MCP tools. This allows you to add, update, and remove database connections without restarting the server.

Available MCP Tools

Tool	Description	Requirements
sql_add_database	Add new database connections at runtime via MCP	None
sql_update_database	Update existing database settings via MCP	mcp_configurable=true on the target database
sql_remove_database	Remove database connections via MCP	mcp_configurable=true on the target database
sql_get_config	View database configuration (passwords are automatically redacted)	None
sql_set_mcp_configurable	Lock a database from MCP changes	One-way operation: can only lock (false), unlocking requires manual config edit

Usage Notes

• Set mcp_configurable=true in your database config to allow MCP-driven updates and removal.
• The sql_set_mcp_configurable tool is a one-way lock: once set to false, the database can no longer be modified or removed via MCP. Unlocking requires a manual edit to the configuration file.
• The sql_get_config tool always redacts passwords and other sensitive fields before returning configuration data.
• Databases added at runtime via sql_add_database have mcp_configurable=true by default.

Performance

Benchmarks

Operation	PostgreSQL	MySQL	SQLite	SQL Server
Simple SELECT	~5ms	~4ms	~1ms	~6ms
Complex JOIN	~45ms	~40ms	~8ms	~50ms
Schema Capture	~150ms	~120ms	~30ms	~180ms
Connection Setup	~80ms	~60ms	~5ms	~100ms

Performance Features

• Connection Pooling - Reuse database connections efficiently
• Schema Caching - Instant metadata access after initial capture
• Query Optimization - Built-in EXPLAIN plan analysis
• Result Streaming - Handle large datasets efficiently
• Batch Operations - Execute multiple queries optimally

CLI Commands

Command	Description
argos-mcp	Start the Argos MCP server on stdio (this is what Claude Code invokes)
argos-setup	Run the interactive configuration wizard

Both are exposed as bin entries, so npm link (or a global install) makes them available on your PATH. Registration with Claude Code is handled by claude mcp add — see Quick Start.

Development

Development Setup

git clone https://github.com/AraneaDev/Argos-MCP.git
cd Argos-MCP
npm install
npm run dev
npm test

Full Development Guide

License

This project is licensed under the MIT License.

Open Source Commitment

• Always free for individual developers and small teams
• No vendor lock-in - use with any Claude deployment
• Transparent development process and roadmap

Acknowledgments

Built With

• TypeScript - Language and tooling
• Node.js - Runtime platform
• Jest - Testing framework
• ESLint - Code quality
• MCP Protocol - AI integration standard

Special Thanks

• Anthropic - For Claude AI and MCP protocol
• TypeScript Team - For excellent tooling
• Database Driver Maintainers - For reliable connectivity libraries

---

<div align="center">

Get Started Now | Documentation

Transform your database interactions with AI-powered SQL intelligence

</div>