floci-mcp

MCP server that lets an AI agent deploy and manage AWS-shaped resources on a local Floci instance — "spin up an EC2 instance with these parameters," "create an S3 bucket and a DynamoDB table," and so on.

What it does

Floci emulates 76 AWS services on http://localhost:4566. floci-mcp exposes that endpoint to any MCP-compatible client as three tools:

• aws_call(service, action, params) — call any AWS API operation (any service, any action) against Floci. This is the core tool: since it's a thin pass-through to the AWS API, it covers all 76 services without a hand-built tool per operation.
• floci_status() — check whether Floci is reachable.
• floci_inventory() — summarize what's currently deployed across S3, DynamoDB, Lambda, EC2, SQS, SNS, ECS, and RDS in one call.

Prerequisites

• Python 3.10+
• A running Floci instance — see the Floci README for floci start or Docker setup.

Install

From a clone (not yet published to PyPI):

git clone https://github.com/Awilliv/floci-mcp.git
cd floci-mcp
pip install -e .

Once published to PyPI:

pip install floci-mcp

Configuration

Environment variables, all optional:

Variable	Default	Purpose
FLOCI_ENDPOINT_URL	http://localhost:4566	Floci's HTTP endpoint
AWS_DEFAULT_REGION	us-east-1	Region passed to every boto3 client
AWS_ACCESS_KEY_ID	test	Credential; a 12-digit value selects a Floci account (multi-account isolation)
AWS_SECRET_ACCESS_KEY	test	Credential (any non-empty value works against Floci)

Usage examples

Once registered with an MCP client, ask the agent things like:

"Spin up an EC2 instance with a t3.micro instance type using ami-00000000"

"Create an S3 bucket called reports and a DynamoDB table called users with a partition key id"

The agent drives these through aws_call — it already knows AWS API parameter shapes, so no per-service tool needs to exist for it to work.

Registering with an MCP client

Claude Code

Setting AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY explicitly here (rather than relying on the launching shell's environment) avoids accidentally signing requests with real AWS credentials if you happen to have them exported elsewhere.

claude mcp add floci -- floci-mcp

Or add to .mcp.json:

{
  "mcpServers": {
    "floci": {
      "command": "floci-mcp",
      "env": {
        "FLOCI_ENDPOINT_URL": "http://localhost:4566",
        "AWS_ACCESS_KEY_ID": "test",
        "AWS_SECRET_ACCESS_KEY": "test"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "floci": {
      "command": "floci-mcp",
      "env": {
        "FLOCI_ENDPOINT_URL": "http://localhost:4566",
        "AWS_ACCESS_KEY_ID": "test",
        "AWS_SECRET_ACCESS_KEY": "test"
      }
    }
  }
}

Open WebUI (via mcpo)

Open WebUI speaks OpenAPI/tool-calling, not MCP directly. Front floci-mcp with mcpo to expose it as an OpenAPI server:

pip install mcpo
mcpo --port 8000 -- floci-mcp

Then in Open WebUI, go to Settings → Tools → Add a Tool Server and add http://localhost:8000. mcpo passes environment variables through to the floci-mcp process it launches, so set FLOCI_ENDPOINT_URL etc. in the shell you run mcpo from before starting it.

Development

pip install -e ".[test]"
pytest

Integration tests in tests/test_integration.py require a running Floci instance and skip themselves automatically when one isn't reachable.

License

MIT