Skip to main content
Glama
floci-mcp
by Awilliv

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.

Related MCP server: AWS MCP Server

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

Available Tools

3 tools
aws_callA

Call any AWS API operation against the local Floci instance. service: boto3 service name (e.g. 'ec2', 's3', 'lambda', 'rds'). action: the AWS API operation name, e.g. 'RunInstances' or 'run_instances'. params: a JSON object of API parameters exactly as AWS documents them, e.g. {"Bucket": "my-bucket"}.

Inputs: action (required), service (required), params.

floci_inventoryA

Summarize resources currently deployed on Floci across common services: S3, DynamoDB, Lambda, EC2, SQS, SNS, ECS, RDS.

Inputs: no named parameters.

floci_statusA

Check whether the configured Floci instance is reachable.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 3 tools

    Disambiguation5/5

    The three tools have clearly distinct purposes: aws_call for arbitrary AWS operations, floci_status for connectivity checks, and floci_inventory for resource summaries. There is no overlap or ambiguity between them.

    Naming Consistency3/5

    Two tools follow a `floci_` snake_case prefix pattern, but `aws_call` uses camelCase and doesn't follow the same convention. The mixed naming style is noticeable but still readable.

    Tool Count5/5

    With only 3 tools, the set is tightly scoped and every tool earns its place. The number is appropriate for a server that provides a generic AWS API pass-through plus convenience utilities.

    Completeness5/5

    The `aws_call` tool covers the full AWS API surface, so any operation can be performed. `floci_status` and `floci_inventory` fill specific monitoring and overview gaps, providing a complete workflow without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers