# Directory Structure
```
├── .env.example
├── .gitignore
├── .python-version
├── LICENSE
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/.python-version:
--------------------------------------------------------------------------------
```
1 | 3.13
2 |
```
--------------------------------------------------------------------------------
/.env.example:
--------------------------------------------------------------------------------
```
1 | AWS_ACCESS_KEY_ID=your_access_key_id
2 | AWS_SECRET_ACCESS_KEY=your_secret_access_key
3 | AWS_REGION=us-east-1
4 | S3_BUCKET_NAME=your_bucket_name
5 | MCP_PORT=8000
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Byte-compiled / optimized / DLL files
2 | __pycache__/
3 | *.py[cod]
4 | *$py.class
5 |
6 | # C extensions
7 | *.so
8 |
9 | # Distribution / packaging
10 | .Python
11 | build/
12 | develop-eggs/
13 | dist/
14 | downloads/
15 | eggs/
16 | .eggs/
17 | lib/
18 | lib64/
19 | parts/
20 | sdist/
21 | var/
22 | wheels/
23 | share/python-wheels/
24 | *.egg-info/
25 | .installed.cfg
26 | *.egg
27 | MANIFEST
28 |
29 | # PyInstaller
30 | # Usually these files are written by a python script from a template
31 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
32 | *.manifest
33 | *.spec
34 |
35 | # Installer logs
36 | pip-log.txt
37 | pip-delete-this-directory.txt
38 |
39 | # Unit test / coverage reports
40 | htmlcov/
41 | .tox/
42 | .nox/
43 | .coverage
44 | .coverage.*
45 | .cache
46 | nosetests.xml
47 | coverage.xml
48 | *.cover
49 | *.py,cover
50 | .hypothesis/
51 | .pytest_cache/
52 | cover/
53 |
54 | # Translations
55 | *.mo
56 | *.pot
57 |
58 | # Django stuff:
59 | *.log
60 | local_settings.py
61 | db.sqlite3
62 | db.sqlite3-journal
63 |
64 | # Flask stuff:
65 | instance/
66 | .webassets-cache
67 |
68 | # Scrapy stuff:
69 | .scrapy
70 |
71 | # Sphinx documentation
72 | docs/_build/
73 |
74 | # PyBuilder
75 | .pybuilder/
76 | target/
77 |
78 | # Jupyter Notebook
79 | .ipynb_checkpoints
80 |
81 | # IPython
82 | profile_default/
83 | ipython_config.py
84 |
85 | # pyenv
86 | # For a library or package, you might want to ignore these files since the code is
87 | # intended to run in multiple environments; otherwise, check them in:
88 | # .python-version
89 |
90 | # pipenv
91 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92 | # However, in case of collaboration, if having platform-specific dependencies or dependencies
93 | # having no cross-platform support, pipenv may install dependencies that don't work, or not
94 | # install all needed dependencies.
95 | #Pipfile.lock
96 |
97 | # UV
98 | # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99 | # This is especially recommended for binary packages to ensure reproducibility, and is more
100 | # commonly ignored for libraries.
101 | #uv.lock
102 |
103 | # poetry
104 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105 | # This is especially recommended for binary packages to ensure reproducibility, and is more
106 | # commonly ignored for libraries.
107 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108 | #poetry.lock
109 |
110 | # pdm
111 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
112 | #pdm.lock
113 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
114 | # in version control.
115 | # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
116 | .pdm.toml
117 | .pdm-python
118 | .pdm-build/
119 |
120 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
121 | __pypackages__/
122 |
123 | # Celery stuff
124 | celerybeat-schedule
125 | celerybeat.pid
126 |
127 | # SageMath parsed files
128 | *.sage.py
129 |
130 | # Environments
131 | .env
132 | .venv
133 | env/
134 | venv/
135 | ENV/
136 | env.bak/
137 | venv.bak/
138 |
139 | # Spyder project settings
140 | .spyderproject
141 | .spyproject
142 |
143 | # Rope project settings
144 | .ropeproject
145 |
146 | # mkdocs documentation
147 | /site
148 |
149 | # mypy
150 | .mypy_cache/
151 | .dmypy.json
152 | dmypy.json
153 |
154 | # Pyre type checker
155 | .pyre/
156 |
157 | # pytype static type analyzer
158 | .pytype/
159 |
160 | # Cython debug symbols
161 | cython_debug/
162 |
163 | # PyCharm
164 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
165 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
166 | # and can be added to the global gitignore or merged into this file. For a more nuclear
167 | # option (not recommended) you can uncomment the following to ignore the entire idea folder.
168 | #.idea/
169 |
170 | # Ruff stuff:
171 | .ruff_cache/
172 |
173 | # PyPI configuration file
174 | .pypirc
175 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # mcp-server-s3
2 |
3 |
4 |
```
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
```toml
1 | [project]
2 | name = "s3-mcp"
3 | version = "0.1.0"
4 | description = "Add your description here"
5 | readme = "README.md"
6 | requires-python = ">=3.13"
7 | dependencies = [
8 | "boto3>=1.37.21",
9 | "dotenv>=0.9.9",
10 | "mcp[cli]>=1.5.0",
11 | ]
12 |
```
--------------------------------------------------------------------------------
/main.py:
--------------------------------------------------------------------------------
```python
1 | import os
2 | from typing import Any
3 | from dotenv import load_dotenv
4 | import boto3
5 | from mcp.server.fastmcp import FastMCP, Context
6 |
7 | # Load environment variables
8 | load_dotenv()
9 |
10 | s3_client = boto3.client(
11 | 's3',
12 | aws_access_key_id=os.getenv('AWS_ACCESS_KEY_ID'),
13 | aws_secret_access_key=os.getenv('AWS_SECRET_ACCESS_KEY'),
14 | region_name=os.getenv('AWS_REGION', 'us-west-1')
15 | )
16 | # Initialize FastMCP server
17 | app = FastMCP("s3")
18 |
19 | @app.tool(name="list_buckets", description="List all buckets")
20 | async def list_buckets(context: Context) -> Any:
21 | try:
22 | # List all buckets
23 | response = s3_client.list_buckets()
24 | buckets = [bucket['Name'] for bucket in response['Buckets']]
25 | return {"buckets": buckets}
26 | except Exception as e:
27 | return {"error": str(e)}
28 |
29 | @app.tool(name="list_bucket", description="List objects in a bucket")
30 | async def list_bucket(context: Context, bucket_name: str, key_prefix: str = ""):
31 | try:
32 | if not bucket_name:
33 | return {"error": "S3_BUCKET_NAME not set"}
34 |
35 | # List objects in the bucket
36 | response = s3_client.list_objects_v2(Bucket=bucket_name, Prefix=key_prefix)
37 | files = []
38 |
39 | if 'Contents' in response:
40 | for obj in response['Contents']:
41 | files.append({
42 | 'key': obj['Key'],
43 | 'size': obj['Size'],
44 | 'last_modified': obj['LastModified'].isoformat()
45 | })
46 |
47 | return {
48 | 'bucket': bucket_name,
49 | 'files': files
50 | }
51 | except Exception as e:
52 | return {"error": str(e)}
53 |
54 | @app.tool(name="get_object", description="Get an object from a bucket")
55 | async def get_object(context: Context, bucket_name: str, key: str):
56 | try:
57 | response = s3_client.get_object(Bucket=bucket_name, Key=key)
58 | return response['Body'].read()
59 | except Exception as e:
60 | return {"error": str(e)}
61 |
62 | @app.tool(name="put_object", description="Put an object into a bucket")
63 | async def put_object(context: Context, bucket_name: str, key: str, body: str):
64 | try:
65 | s3_client.put_object(Bucket=bucket_name, Key=key, Body=body)
66 | return {"success": True}
67 | except Exception as e:
68 | return {"error": str(e)}
69 |
70 | @app.tool(name="upload_local_file", description="Upload a local file to a bucket")
71 | async def upload_local_file(context: Context, bucket_name: str, local_path: str, key: str):
72 | try:
73 | s3_client.upload_file(local_path, bucket_name, key)
74 | return {"success": True}
75 | except Exception as e:
76 | return {"error": str(e)}
77 |
78 | @app.tool(name="download_file_to_local", description="Download a file from a bucket to a local path")
79 | async def download_file_to_local(context: Context, bucket_name: str, key: str, local_path: str):
80 | try:
81 | s3_client.download_file(bucket_name, key, local_path)
82 | return {"success": True}
83 | except Exception as e:
84 | return {"error": str(e)}
85 |
86 | @app.tool(name="delete_object", description="Delete an object from a bucket")
87 | async def delete_object(context: Context, bucket_name: str, key: str):
88 | try:
89 | s3_client.delete_object(Bucket=bucket_name, Key=key)
90 | return {"success": True}
91 | except Exception as e:
92 | return {"error": str(e)}
93 |
94 | if __name__ == "__main__":
95 | app.run(transport='stdio')
96 |
```